Defines the calculation engine for date and time fields.
The interface defines a set of methods that manipulate a millisecond datetime
with regards to a single field, such as monthOfYear or secondOfMinute.

This design is extensible so, if you wish, you can extract a different field from
the milliseconds. A number of standard implementations are provided to assist.

By convention, names follow a pattern of "dddOfRrr", where "ddd" represents
the (singular) duration unit field name and "Rrr" represents the (singular)
duration range field name. If the range field is not applicable, then
the name of the field is simply the (singular) duration field name.

Adds a value (which may be negative) to the millis value,
overflowing into larger fields if necessary.

The value will be added to this field. If the value is too large to be
added solely to this field, larger fields will increase as required.
Smaller fields should be unaffected, except where the result would be
an invalid value for a smaller field. In this case the smaller field is
adjusted to be in range.

Adds a value (which may be negative) to the partial instant,
throwing an exception if the maximum size of the instant is reached.

The value will be added to this field, overflowing into larger fields
if necessary. Smaller fields should be unaffected, except where the
result would be an invalid value for a smaller field. In this case the
smaller field is adjusted to be in range.

Partial instants only contain some fields. This may result in a maximum
possible value, such as TimeOfDay being limited to 23:59:59:999. If this
limit is breached by the add an exception is thrown.

Adds a value (which may be negative) to the partial instant,
wrapping the whole partial if the maximum size of the partial is reached.

The value will be added to this field, overflowing into larger fields
if necessary. Smaller fields should be unaffected, except where the
result would be an invalid value for a smaller field. In this case the
smaller field is adjusted to be in range.

Partial instants only contain some fields. This may result in a maximum
possible value, such as TimeOfDay normally being limited to 23:59:59:999.
If ths limit is reached by the addition, this method will wrap back to
00:00:00.000. In fact, you would generally only use this method for
classes that have a limitation such as this.

Adds a value (which may be negative) to the millis value,
wrapping within this field.

The value will be added to this field. If the value is too large to be
added solely to this field then it wraps. Larger fields are always
unaffected. Smaller fields should be unaffected, except where the
result would be an invalid value for a smaller field. In this case the
smaller field is adjusted to be in range.

Adds a value (which may be negative) to the partial instant,
wrapping within this field.

The value will be added to this field. If the value is too large to be
added solely to this field then it wraps. Larger fields are always
unaffected. Smaller fields should be unaffected, except where the
result would be an invalid value for a smaller field. In this case the
smaller field is adjusted to be in range.

Computes the difference between two instants, as measured in the units
of this field. Any fractional units are dropped from the result. Calling
getDifference reverses the effect of calling add. In the following code:

Computes the difference between two instants, as measured in the units
of this field. Any fractional units are dropped from the result. Calling
getDifference reverses the effect of calling add. In the following code:

The value of this field will be set.
If the value is invalid, an exception if thrown.

If setting this field would make other fields invalid, then those fields
may be changed. For example if the current date is the 31st January, and
the month is set to February, the day would be invalid. Instead, the day
would be changed to the closest value - the 28th/29th February as appropriate.

The value of this field (specified by the index) will be set.
If the value is invalid, an exception if thrown.

If setting this field would make other fields invalid, then those fields
may be changed. For example if the current date is the 31st January, and
the month is set to February, the day would be invalid. Instead, the day
would be changed to the closest value - the 28th/29th February as appropriate.

Sets a value in the milliseconds supplied from a human-readable, text value.
If the specified locale is null, the default locale is used.

If setting this field would make other fields invalid, then those fields
may be changed. For example if the current date is the 31st January, and
the month is set to February, the day would be invalid. Instead, the day
would be changed to the closest value - the 28th/29th February as appropriate.

Parameters:

instant the milliseconds from 1970-01-01T00:00:00Z to set in

text the text value to set

locale the locale to use for selecting a text symbol, null for default

Sets a value in the milliseconds supplied from a human-readable, text value.

If setting this field would make other fields invalid, then those fields
may be changed. For example if the current date is the 31st January, and
the month is set to February, the day would be invalid. Instead, the day
would be changed to the closest value - the 28th/29th February as appropriate.

Sets a value in the milliseconds supplied from a human-readable, text value.
If the specified locale is null, the default locale is used.

If setting this field would make other fields invalid, then those fields
may be changed. For example if the current date is the 31st January, and
the month is set to February, the day would be invalid. Instead, the day
would be changed to the closest value - the 28th/29th February as appropriate.

Parameters:

instant the partial instant

fieldIndex the index of this field in the instant

values the values of the partial instant which should be updated

text the text value to set

locale the locale to use for selecting a text symbol, null for default

Round to the lowest whole unit of this field. After rounding, the value
of this field and all fields of a higher magnitude are retained. The
fractional millis that cannot be expressed in whole increments of this
field are set to minimum.

For example, a datetime of 2002-11-02T23:34:56.789, rounded to the
lowest whole hour is 2002-11-02T23:00:00.000.

Round to the highest whole unit of this field. The value of this field
and all fields of a higher magnitude may be incremented in order to
achieve this result. The fractional millis that cannot be expressed in
whole increments of this field are set to minimum.

For example, a datetime of 2002-11-02T23:34:56.789, rounded to the
highest whole hour is 2002-11-03T00:00:00.000.

Round to the nearest whole unit of this field. If the given millisecond
value is closer to the floor or is exactly halfway, this function
behaves like roundFloor. If the millisecond value is closer to the
ceiling, this function behaves like roundCeiling.

Round to the nearest whole unit of this field. If the given millisecond
value is closer to the floor, this function behaves like roundFloor. If
the millisecond value is closer to the ceiling or is exactly halfway,
this function behaves like roundCeiling.

Round to the nearest whole unit of this field. If the given millisecond
value is closer to the floor, this function behaves like roundFloor. If
the millisecond value is closer to the ceiling, this function behaves
like roundCeiling.

If the millisecond value is exactly halfway between the floor and
ceiling, the ceiling is chosen over the floor only if it makes this
field's value even.