A time with an offset from UTC/Greenwich in the ISO-8601 calendar system,
such as 10:15:30+01:00.

OffsetTime is an immutable date-time object that represents a time, often
viewed as hour-minute-second-offset.
This class stores all time fields, to a precision of nanoseconds,
as well as a zone offset.
For example, the value "13:45.30.123456789+02:00" can be stored
in an OffsetTime.

This is a value-based
class; use of identity-sensitive operations (including reference equality
(==), identity hash code, or synchronization) on instances of
OffsetTime may have unpredictable results and should be avoided.
The equals method should be used for comparisons.

Field Detail

MIN

The minimum supported OffsetTime, '00:00:00+18:00'.
This is the time of midnight at the start of the day in the maximum offset
(larger offsets are earlier on the time-line).
This combines LocalTime.MIN and ZoneOffset.MAX.
This could be used by an application as a "far past" date.

MAX

The maximum supported OffsetTime, '23:59:59.999999999-18:00'.
This is the time just before midnight at the end of the day in the minimum offset
(larger negative offsets are later on the time-line).
This combines LocalTime.MAX and ZoneOffset.MIN.
This could be used by an application as a "far future" date.

of

Obtains an instance of OffsetTime from an hour, minute, second and nanosecond.

This creates an offset time with the four specified fields.

This method exists primarily for writing test cases.
Non test-code will typically use other methods to create an offset time.
LocalTime has two additional convenience variants of the
equivalent factory method taking fewer arguments.
They are not provided here to reduce the footprint of the API.

from

This obtains an offset time based on the specified temporal.
A TemporalAccessor represents an arbitrary set of date and time information,
which this factory converts to an instance of OffsetTime.

The conversion extracts and combines the ZoneOffset and the
LocalTime from the temporal object.
Implementations are permitted to perform optimizations such as accessing
those fields that are equivalent to the relevant objects.

This method matches the signature of the functional interface TemporalQuery
allowing it to be used in queries via method reference, OffsetTime::from.

isSupported

This checks if this time can be queried for the specified field.
If false, then calling the range,
get and with(TemporalField, long)
methods will throw an exception.

If the field is a ChronoField then the query is implemented here.
The supported fields are:

NANO_OF_SECOND

NANO_OF_DAY

MICRO_OF_SECOND

MICRO_OF_DAY

MILLI_OF_SECOND

MILLI_OF_DAY

SECOND_OF_MINUTE

SECOND_OF_DAY

MINUTE_OF_HOUR

MINUTE_OF_DAY

HOUR_OF_AMPM

CLOCK_HOUR_OF_AMPM

HOUR_OF_DAY

CLOCK_HOUR_OF_DAY

AMPM_OF_DAY

OFFSET_SECONDS

All other ChronoField instances will return false.

If the field is not a ChronoField, then the result of this method
is obtained by invoking TemporalField.isSupportedBy(TemporalAccessor)
passing this as the argument.
Whether the field is supported is determined by the field.

isSupported

This checks if the specified unit can be added to, or subtracted from, this date-time.
If false, then calling the plus(long, TemporalUnit) and
minus methods will throw an exception.

If the unit is a ChronoUnit then the query is implemented here.
The supported units are:

NANOS

MICROS

MILLIS

SECONDS

MINUTES

HOURS

HALF_DAYS

All other ChronoUnit instances will return false.

If the unit is not a ChronoUnit, then the result of this method
is obtained by invoking TemporalUnit.isSupportedBy(Temporal)
passing this as the argument.
Whether the unit is supported is determined by the unit.

range

The range object expresses the minimum and maximum valid values for a field.
This time is used to enhance the accuracy of the returned range.
If it is not possible to return the range, because the field is not supported
or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here.
The supported fields will return
appropriate range instances.
All other ChronoField instances will throw an UnsupportedTemporalTypeException.

If the field is not a ChronoField, then the result of this method
is obtained by invoking TemporalField.rangeRefinedBy(TemporalAccessor)
passing this as the argument.
Whether the range can be obtained is determined by the field.

get

This queries this time for the value for the specified field.
The returned value will always be within the valid range of values for the field.
If it is not possible to return the value, because the field is not supported
or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here.
The supported fields will return valid
values based on this time, except NANO_OF_DAY and MICRO_OF_DAY
which are too large to fit in an int and throw a DateTimeException.
All other ChronoField instances will throw an UnsupportedTemporalTypeException.

If the field is not a ChronoField, then the result of this method
is obtained by invoking TemporalField.getFrom(TemporalAccessor)
passing this as the argument. Whether the value can be obtained,
and what the value represents, is determined by the field.

getLong

This queries this time for the value for the specified field.
If it is not possible to return the value, because the field is not supported
or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here.
The supported fields will return valid
values based on this time.
All other ChronoField instances will throw an UnsupportedTemporalTypeException.

If the field is not a ChronoField, then the result of this method
is obtained by invoking TemporalField.getFrom(TemporalAccessor)
passing this as the argument. Whether the value can be obtained,
and what the value represents, is determined by the field.

withOffsetSameLocal

Returns a copy of this OffsetTime with the specified offset ensuring
that the result has the same local time.

This method returns an object with the same LocalTime and the specified ZoneOffset.
No calculation is needed or performed.
For example, if this time represents 10:30+02:00 and the offset specified is
+03:00, then this method will return 10:30+03:00.

withOffsetSameInstant

Returns a copy of this OffsetTime with the specified offset ensuring
that the result is at the same instant on an implied day.

This method returns an object with the specified ZoneOffset and a LocalTime
adjusted by the difference between the two offsets.
This will result in the old and new objects representing the same instant an an implied day.
This is useful for finding the local time in a different offset.
For example, if this time represents 10:30+02:00 and the offset specified is
+03:00, then this method will return 11:30+03:00.

getNano

with

This returns an OffsetTime, based on this one, with the time adjusted.
The adjustment takes place using the specified adjuster strategy object.
Read the documentation of the adjuster to understand what adjustment will be made.

A simple adjuster might simply set the one of the fields, such as the hour field.
A more complex adjuster might set the time to the last hour of the day.

The classes LocalTime and ZoneOffset implement TemporalAdjuster,
thus this method can be used to change the time or offset:

with

Returns a copy of this time with the specified field set to a new value.

This returns an OffsetTime, based on this one, with the value
for the specified field changed.
This can be used to change any supported field, such as the hour, minute or second.
If it is not possible to set the value, because the field is not supported or for
some other reason, an exception is thrown.

If the field is a ChronoField then the adjustment is implemented here.

The OFFSET_SECONDS field will return a time with the specified offset.
The local time is unaltered. If the new offset value is outside the valid range
then a DateTimeException will be thrown.

All other ChronoField instances will throw an UnsupportedTemporalTypeException.

If the field is not a ChronoField, then the result of this method
is obtained by invoking TemporalField.adjustInto(Temporal, long)
passing this as the argument. In this case, the field determines
whether and how to adjust the instant.

truncatedTo

Truncation returns a copy of the original time with fields
smaller than the specified unit set to zero.
For example, truncating with the minutes unit
will set the second-of-minute and nano-of-second field to zero.

The unit must have a duration
that divides into the length of a standard day without remainder.
This includes all supplied time units on ChronoUnit and
DAYS. Other units throw an exception.

The offset does not affect the calculation and will be the same in the result.

plus

This returns an OffsetTime, based on this one, with the specified amount added.
The amount is typically Duration but may be any other type implementing
the TemporalAmount interface.

The calculation is delegated to the amount object by calling
TemporalAmount.addTo(Temporal). The amount implementation is free
to implement the addition in any way it wishes, however it typically
calls back to plus(long, TemporalUnit). Consult the documentation
of the amount implementation to determine if it can be successfully added.

plus

This returns an OffsetTime, based on this one, with the amount
in terms of the unit added. If it is not possible to add the amount, because the
unit is not supported or for some other reason, an exception is thrown.

If the field is not a ChronoUnit, then the result of this method
is obtained by invoking TemporalUnit.addTo(Temporal, long)
passing this as the argument. In this case, the unit determines
whether and how to perform the addition.

minus

This returns an OffsetTime, based on this one, with the specified amount subtracted.
The amount is typically Duration but may be any other type implementing
the TemporalAmount interface.

The calculation is delegated to the amount object by calling
TemporalAmount.subtractFrom(Temporal). The amount implementation is free
to implement the subtraction in any way it wishes, however it typically
calls back to minus(long, TemporalUnit). Consult the documentation
of the amount implementation to determine if it can be successfully subtracted.

minus

This returns an OffsetTime, based on this one, with the amount
in terms of the unit subtracted. If it is not possible to subtract the amount,
because the unit is not supported or for some other reason, an exception is thrown.

This method is equivalent to plus(long, TemporalUnit) with the amount negated.
See that method for a full description of how addition, and thus subtraction, works.

query

This queries this time using the specified query strategy object.
The TemporalQuery object defines the logic to be used to
obtain the result. Read the documentation of the query to understand
what the result of this method will be.

until

Calculates the amount of time until another time in terms of the specified unit.

This calculates the amount of time between two OffsetTime
objects in terms of a single TemporalUnit.
The start and end points are this and the specified time.
The result will be negative if the end is before the start.
For example, the period in hours between two times can be calculated
using startTime.until(endTime, HOURS).

The Temporal passed to this method is converted to a
OffsetTime using from(TemporalAccessor).
If the offset differs between the two times, then the specified
end time is normalized to have the same offset as this time.

The calculation returns a whole number, representing the number of
complete units between the two times.
For example, the period in hours between 11:30Z and 13:29Z will only
be one hour as it is one minute short of two hours.

The choice should be made based on which makes the code more readable.

The calculation is implemented in this method for ChronoUnit.
The units NANOS, MICROS, MILLIS, SECONDS,
MINUTES, HOURS and HALF_DAYS are supported.
Other ChronoUnit values will throw an exception.

If the unit is not a ChronoUnit, then the result of this method
is obtained by invoking TemporalUnit.between(Temporal, Temporal)
passing this as the first argument and the converted input temporal
as the second argument.

compareTo

The comparison is based first on the UTC equivalent instant, then on the local time.
It is "consistent with equals", as defined by Comparable.

For example, the following is the comparator order:

10:30+01:00

11:00+01:00

12:00+02:00

11:30+01:00

12:00+01:00

12:30+01:00

Values #2 and #3 represent the same instant on the time-line.
When two values represent the same instant, the local time is compared
to distinguish them. This step is needed to make the ordering
consistent with equals().

To compare the underlying local time of two TemporalAccessor instances,
use ChronoField.NANO_OF_DAY as a comparator.

isAfter

Checks if the instant of this OffsetTime is after that of the
specified time applying both times to a common date.

This method differs from the comparison in compareTo(java.time.OffsetTime) in that it
only compares the instant of the time. This is equivalent to converting both
times to an instant using the same date and comparing the instants.

Parameters:

other - the other time to compare to, not null

Returns:

true if this is after the instant of the specified time

isBefore

Checks if the instant of this OffsetTime is before that of the
specified time applying both times to a common date.

This method differs from the comparison in compareTo(java.time.OffsetTime) in that it
only compares the instant of the time. This is equivalent to converting both
times to an instant using the same date and comparing the instants.