org.joda.time

Class DateTime.Property

java.lang.Object

org.joda.time.field.AbstractReadableInstantFieldProperty

org.joda.time.DateTime.Property

All Implemented Interfaces:

java.io.Serializable

Enclosing class:

DateTime

public static final class DateTime.Property
extends AbstractReadableInstantFieldProperty

DateTime.Property binds a DateTime to a DateTimeField allowing powerful datetime functionality to be easily accessed.

The simplest use of this class is as an alternative get method, here used to get the year '1972' (as an int) and the month 'December' (as a String).

 DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
 int year = dt.year().get();
 String monthStr = dt.month().getAsText();
 

Methods are also provided that allow date modification. These return new instances of DateTime - they do not modify the original. The example below yields two independent immutable date objects 20 years apart.

 DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
 DateTime dt20 = dt.year().addToCopy(20);
 

Serious modification of dates (ie. more than just changing one or two fields) should use the MutableDateTime class.

DateTime.Propery itself is thread-safe and immutable, as well as the DateTime being operated on.

Since:

1.0

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
DateTime	addToCopy(int value) Adds to this field in a copy of this DateTime.
DateTime	addToCopy(long value) Adds to this field in a copy of this DateTime.
DateTime	addWrapFieldToCopy(int value) Adds to this field, possibly wrapped, in a copy of this DateTime.
DateTime	getDateTime() Gets the datetime being used.
DateTimeField	getField() Gets the field being used.
DateTime	roundCeilingCopy() Rounds to the highest whole unit of this field on a copy of this DateTime.
DateTime	roundFloorCopy() Rounds to the lowest whole unit of this field on a copy of this DateTime.
DateTime	roundHalfCeilingCopy() Rounds to the nearest whole unit of this field on a copy of this DateTime, favoring the ceiling if halfway.
DateTime	roundHalfEvenCopy() Rounds to the nearest whole unit of this field on a copy of this DateTime.
DateTime	roundHalfFloorCopy() Rounds to the nearest whole unit of this field on a copy of this DateTime, favoring the floor if halfway.
DateTime	setCopy(int value) Sets this field in a copy of the DateTime.
DateTime	setCopy(java.lang.String text) Sets this field in a copy of the DateTime to a parsed text value.
DateTime	setCopy(java.lang.String text, java.util.Locale locale) Sets this field in a copy of the DateTime to a parsed text value.
DateTime	withMaximumValue() Returns a new DateTime with this field set to the maximum value for this field.
DateTime	withMinimumValue() Returns a new DateTime with this field set to the minimum value for this field.

Methods inherited from class org.joda.time.field.AbstractReadableInstantFieldProperty

compareTo, compareTo, equals, get, getAsShortText, getAsShortText, getAsString, getAsText, getAsText, getDifference, getDifferenceAsLong, getDurationField, getFieldType, getLeapAmount, getLeapDurationField, getMaximumShortTextLength, getMaximumTextLength, getMaximumValue, getMaximumValueOverall, getMinimumValue, getMinimumValueOverall, getName, getRangeDurationField, hashCode, isLeap, remainder, toInterval, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

getField

public DateTimeField getField()

Gets the field being used.

Specified by:

getField in class AbstractReadableInstantFieldProperty

Returns:

the field

getDateTime

public DateTime getDateTime()

Gets the datetime being used.

Returns:

the datetime

addToCopy

public DateTime addToCopy(int value)

Adds to this field in a copy of this DateTime.

The DateTime attached to this property is unchanged by this call. This operation is faster than converting a DateTime to a MutableDateTime and back again when setting one field. When setting multiple fields, it is generally quicker to make the conversion to MutableDateTime.

Parameters:

value - the value to add to the field in the copy

Returns:

a copy of the DateTime with the field value changed

Throws:

java.lang.IllegalArgumentException - if the value isn't valid

addToCopy

public DateTime addToCopy(long value)

Adds to this field in a copy of this DateTime.

The DateTime attached to this property is unchanged by this call. This operation is faster than converting a DateTime to a MutableDateTime and back again when setting one field. When setting multiple fields, it is generally quicker to make the conversion to MutableDateTime.

Parameters:

value - the value to add to the field in the copy

Returns:

a copy of the DateTime with the field value changed

Throws:

java.lang.IllegalArgumentException - if the value isn't valid

addWrapFieldToCopy

public DateTime addWrapFieldToCopy(int value)

Adds to this field, possibly wrapped, in a copy of this DateTime. A wrapped operation only changes this field. Thus 31st January addWrapField one day goes to the 1st January.

The DateTime attached to this property is unchanged by this call. This operation is faster than converting a DateTime to a MutableDateTime and back again when setting one field. When setting multiple fields, it is generally quicker to make the conversion to MutableDateTime.

Parameters:

value - the value to add to the field in the copy

Returns:

a copy of the DateTime with the field value changed

Throws:

java.lang.IllegalArgumentException - if the value isn't valid

setCopy

public DateTime setCopy(int value)

Sets this field in a copy of the DateTime.

The DateTime attached to this property is unchanged by this call. This operation is faster than converting a DateTime to a MutableDateTime and back again when setting one field. When setting multiple fields, it is generally quicker to make the conversion to MutableDateTime.

Parameters:

value - the value to set the field in the copy to

Returns:

a copy of the DateTime with the field value changed

Throws:

java.lang.IllegalArgumentException - if the value isn't valid

setCopy

public DateTime setCopy(java.lang.String text,
                        java.util.Locale locale)

Sets this field in a copy of the DateTime to a parsed text value.

The DateTime attached to this property is unchanged by this call. This operation is faster than converting a DateTime to a MutableDateTime and back again when setting one field. When setting multiple fields, it is generally quicker to make the conversion to MutableDateTime.

Parameters:

text - the text value to set

locale - optional locale to use for selecting a text symbol

Returns:

a copy of the DateTime with the field value changed

Throws:

java.lang.IllegalArgumentException - if the text value isn't valid

setCopy

public DateTime setCopy(java.lang.String text)

Sets this field in a copy of the DateTime to a parsed text value.

The DateTime attached to this property is unchanged by this call. This operation is faster than converting a DateTime to a MutableDateTime and back again when setting one field. When setting multiple fields, it is generally quicker to make the conversion to MutableDateTime.

Parameters:

text - the text value to set

Returns:

a copy of the DateTime with the field value changed

Throws:

java.lang.IllegalArgumentException - if the text value isn't valid

withMaximumValue

public DateTime withMaximumValue()

Returns a new DateTime with this field set to the maximum value for this field.

This operation is useful for obtaining a DateTime on the last day of the month, as month lengths vary.

 DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();
 

Where possible, the offset from UTC will be retained, thus applications may need to call DateTime.withLaterOffsetAtOverlap() on the result to force the later time during a DST overlap if desired.

From v2.2, this method handles a daylight svaings time gap, setting the time to the last instant before the gap.

The DateTime attached to this property is unchanged by this call.

Returns:

a copy of the DateTime with this field set to its maximum

Since:

1.2

withMinimumValue

public DateTime withMinimumValue()

Returns a new DateTime with this field set to the minimum value for this field.

Where possible, the offset from UTC will be retained, thus applications may need to call DateTime.withEarlierOffsetAtOverlap() on the result to force the earlier time during a DST overlap if desired.

From v2.2, this method handles a daylight svaings time gap, setting the time to the first instant after the gap.

The DateTime attached to this property is unchanged by this call.

Returns:

a copy of the DateTime with this field set to its minimum

Since:

1.2

roundFloorCopy

public DateTime roundFloorCopy()

Rounds to the lowest whole unit of this field on a copy of this DateTime.

Returns:

a copy of the DateTime with the field value changed

roundCeilingCopy

public DateTime roundCeilingCopy()

Rounds to the highest whole unit of this field on a copy of this DateTime.

Returns:

a copy of the DateTime with the field value changed

roundHalfFloorCopy

public DateTime roundHalfFloorCopy()

Rounds to the nearest whole unit of this field on a copy of this DateTime, favoring the floor if halfway.

Returns:

a copy of the DateTime with the field value changed

roundHalfCeilingCopy

public DateTime roundHalfCeilingCopy()

Rounds to the nearest whole unit of this field on a copy of this DateTime, favoring the ceiling if halfway.

Returns:

a copy of the DateTime with the field value changed

roundHalfEvenCopy

public DateTime roundHalfEvenCopy()

Rounds to the nearest whole unit of this field on a copy of this DateTime. If halfway, the ceiling is favored over the floor only if it makes this field's value even.

Returns:

a copy of the DateTime with the field value changed