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.
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.
value
- the value to add to the field in the copy
- a copy of the DateTime with the field value changed
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.
value
- the value to add to the field in the copy
- a copy of the DateTime with the field value changed
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.
value
- the value to add to the field in the copy
- a copy of the DateTime with the field value changed
getDateTime
public DateTime getDateTime()
Gets the datetime being used.
roundCeilingCopy
public DateTime roundCeilingCopy()
Rounds to the highest whole unit of this field on a copy of this DateTime.
- a copy of the DateTime with the field value changed
roundFloorCopy
public DateTime roundFloorCopy()
Rounds to the lowest whole unit of this field on a copy of this DateTime.
- 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.
- 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.
- 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.
- a copy of the DateTime with the field value changed
setCopy
public DateTime setCopy(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.
text
- the text value to set
- a copy of the DateTime with the field value changed
setCopy
public DateTime setCopy(String text,
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.
text
- the text value to setlocale
- optional locale to use for selecting a text symbol
- a copy of the DateTime with the field value changed
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.
value
- the value to set the field in the copy to
- a copy of the DateTime with the field value changed
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();
The DateTime attached to this property is unchanged by this call.
- a copy of the DateTime with this field set to its maximum
withMinimumValue
public DateTime withMinimumValue()
Returns a new DateTime with this field set to the minimum value
for this field.
The DateTime attached to this property is unchanged by this call.
- a copy of the DateTime with this field set to its minimum