public final class OffsetTime extends Object implements TimeProvider, Calendrical, Comparable<OffsetTime>, Serializable, CalendricalMatcher, TimeAdjuster
10:15:30+01:00
.
OffsetTime
is an immutable calendrical 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.
Thus, for example, the value "13:45.30.123456789+02:00" can be stored
in a OffsetTime
.
OffsetTime is immutable and thread-safe.
Modifier and Type | Method and Description |
---|---|
LocalTime |
adjustTime(LocalTime time)
Adjusts a time to have the value of the time part of this object.
|
int |
compareTo(OffsetTime other)
Compares this
OffsetTime to another time based on the UTC equivalent times
then local time. |
boolean |
equalInstant(OffsetTime other)
Checks if the instant of this
OffsetTime is equal to that of the
specified time applying both times to a common date. |
boolean |
equals(Object other)
Checks if this
OffsetTime is equal to the specified time. |
<T> T |
get(CalendricalRule<T> rule)
Gets the value of the specified calendrical rule.
|
ISOChronology |
getChronology()
Gets the chronology that this time uses, which is the ISO calendar system.
|
int |
getHourOfDay()
Gets the hour-of-day field.
|
int |
getMinuteOfHour()
Gets the minute-of-hour field.
|
int |
getNanoOfSecond()
Gets the nano-of-second field.
|
ZoneOffset |
getOffset()
Gets the zone offset representing how far ahead or behind UTC the time is.
|
int |
getSecondOfMinute()
Gets the second-of-minute field.
|
int |
hashCode()
A hash code for this
OffsetTime . |
boolean |
isAfter(OffsetTime other)
Checks if the instant of this
OffsetTime is after that of the
specified time applying both times to a common date. |
boolean |
isBefore(OffsetTime other)
Checks if the instant of this
OffsetTime is before that of the
specified time applying both times to a common date. |
boolean |
matches(CalendricalMatcher matcher)
Checks whether this
OffsetTime matches the specified matcher. |
boolean |
matchesCalendrical(Calendrical calendrical)
Checks if the time extracted from the calendrical matches this.
|
OffsetTime |
minus(Duration duration)
Returns a copy of this
OffsetTime with the specified duration subtracted. |
OffsetTime |
minus(PeriodProvider periodProvider)
Returns a copy of this
OffsetTime with the specified period subtracted. |
OffsetTime |
minusHours(long hours)
Returns a copy of this
OffsetTime with the specified period in hours subtracted. |
OffsetTime |
minusMinutes(long minutes)
Returns a copy of this
OffsetTime with the specified period in minutes subtracted. |
OffsetTime |
minusNanos(long nanos)
Returns a copy of this
OffsetTime with the specified period in nanoseconds subtracted. |
OffsetTime |
minusSeconds(long seconds)
Returns a copy of this
OffsetTime with the specified period in seconds subtracted. |
static OffsetTime |
now()
Obtains the current time from the system clock in the default time-zone.
|
static OffsetTime |
now(Clock clock)
Obtains the current time from the specified clock.
|
static OffsetTime |
of(int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int nanoOfSecond,
ZoneOffset offset)
Obtains an instance of
OffsetTime from an hour, minute, second and nanosecond. |
static OffsetTime |
of(int hourOfDay,
int minuteOfHour,
int secondOfMinute,
ZoneOffset offset)
Obtains an instance of
OffsetTime from an hour, minute and second. |
static OffsetTime |
of(int hourOfDay,
int minuteOfHour,
ZoneOffset offset)
Obtains an instance of
OffsetTime from an hour and minute. |
static OffsetTime |
of(TimeProvider timeProvider,
ZoneOffset offset)
Obtains an instance of
OffsetTime from a time provider. |
static OffsetTime |
ofInstant(InstantProvider instantProvider,
ZoneOffset offset)
Obtains an instance of
OffsetTime from an InstantProvider . |
static OffsetTime |
parse(String text)
Obtains an instance of
OffsetTime from a text string such as 10:15:30+01:00 . |
static OffsetTime |
parse(String text,
DateTimeFormatter formatter)
Obtains an instance of
OffsetTime from a text string using a specific formatter. |
OffsetTime |
plus(Duration duration)
Returns a copy of this
OffsetTime with the specified duration added. |
OffsetTime |
plus(PeriodProvider periodProvider)
Returns a copy of this
OffsetTime with the specified period added. |
OffsetTime |
plusHours(long hours)
Returns a copy of this
OffsetTime with the specified period in hours added. |
OffsetTime |
plusMinutes(long minutes)
Returns a copy of this
OffsetTime with the specified period in minutes added. |
OffsetTime |
plusNanos(long nanos)
Returns a copy of this
OffsetTime with the specified period in nanoseconds added. |
OffsetTime |
plusSeconds(long seconds)
Returns a copy of this
OffsetTime with the specified period in seconds added. |
static CalendricalRule<OffsetTime> |
rule()
Gets the rule for
OffsetTime . |
LocalTime |
toLocalTime()
Converts this time to a
LocalTime . |
String |
toString()
Outputs this time as a
String , such as 10:15:30+01:00 . |
String |
toString(DateTimeFormatter formatter)
Outputs this time as a
String using the formatter. |
OffsetTime |
with(TimeAdjuster adjuster)
Returns a copy of this
OffsetTime with the time altered using the adjuster. |
OffsetTime |
withHourOfDay(int hourOfDay)
Returns a copy of this
OffsetTime with the hour-of-day value altered. |
OffsetTime |
withMinuteOfHour(int minuteOfHour)
Returns a copy of this
OffsetTime with the minute-of-hour value altered. |
OffsetTime |
withNanoOfSecond(int nanoOfSecond)
Returns a copy of this
OffsetTime with the nano-of-second value altered. |
OffsetTime |
withOffsetSameInstant(ZoneOffset offset)
Returns a copy of this
OffsetTime with the specified offset ensuring
that the result is at the same instant on an implied day. |
OffsetTime |
withOffsetSameLocal(ZoneOffset offset)
Returns a copy of this
OffsetTime with the specified offset ensuring
that the result has the same local time. |
OffsetTime |
withSecondOfMinute(int secondOfMinute)
Returns a copy of this
OffsetTime with the second-of-minute value altered. |
OffsetTime |
withTime(TimeProvider timeProvider)
Returns a copy of this
OffsetTime with the time altered and the offset retained. |
public static OffsetTime now()
This will query the system clock
in the default
time-zone to obtain the current time.
The offset will be calculated from the time-zone in the clock.
Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.
public static OffsetTime now(Clock clock)
This will query the specified clock to obtain the current time. The offset will be calculated from the time-zone in the clock.
Using this method allows the use of an alternate clock for testing.
The alternate clock may be introduced using dependency injection
.
clock
- the clock to use, not nullpublic static OffsetTime of(int hourOfDay, int minuteOfHour, ZoneOffset offset)
OffsetTime
from an hour and minute.
The second and nanosecond fields will be set to zero by this factory method.
hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59offset
- the zone offset, not nullIllegalCalendarFieldValueException
- if the value of any field is out of rangepublic static OffsetTime of(int hourOfDay, int minuteOfHour, int secondOfMinute, ZoneOffset offset)
OffsetTime
from an hour, minute and second.
The second field will be set to zero by this factory method.
hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- the second-of-minute to represent, from 0 to 59offset
- the zone offset, not nullIllegalCalendarFieldValueException
- if the value of any field is out of rangepublic static OffsetTime of(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, ZoneOffset offset)
OffsetTime
from an hour, minute, second and nanosecond.hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59secondOfMinute
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999offset
- the zone offset, not nullIllegalCalendarFieldValueException
- if the value of any field is out of rangepublic static OffsetTime of(TimeProvider timeProvider, ZoneOffset offset)
OffsetTime
from a time provider.timeProvider
- the time provider to use, not nulloffset
- the zone offset, not nullpublic static OffsetTime ofInstant(InstantProvider instantProvider, ZoneOffset offset)
OffsetTime
from an InstantProvider
.
The date component of the instant is dropped during the conversion. This means that the conversion can never fail due to the instant being out of the valid range of dates.
instantProvider
- the instant to convert, not nulloffset
- the zone offset, not nullpublic static OffsetTime parse(String text)
OffsetTime
from a text string such as 10:15:30+01:00
.
The following formats are accepted in ASCII:
{Hour}:{Minute}{OffsetID}
{Hour}:{Minute}:{Second}{OffsetID}
{Hour}:{Minute}:{Second}.{NanosecondFraction}{OffsetID}
The hour has 2 digits with values from 0 to 23. The minute has 2 digits with values from 0 to 59. The second has 2 digits with values from 0 to 59. The nanosecond fraction has from 1 to 9 digits with values from 0 to 999,999,999.
The offset ID is the normalized form as defined in ZoneOffset
.
text
- the text to parse such as '10:15:30+01:00', not nullCalendricalException
- if the text cannot be parsedpublic static OffsetTime parse(String text, DateTimeFormatter formatter)
OffsetTime
from a text string using a specific formatter.
The text is parsed using the formatter, returning a time.
text
- the text to parse, not nullformatter
- the formatter to use, not nullUnsupportedOperationException
- if the formatter cannot parseCalendricalException
- if the text cannot be parsedpublic ISOChronology getChronology()
public <T> T get(CalendricalRule<T> rule)
This method queries the value of the specified calendrical rule.
If the value cannot be returned for the rule from this time then
null
will be returned.
get
in interface Calendrical
rule
- the rule to use, not nullpublic OffsetTime withTime(TimeProvider timeProvider)
OffsetTime
with the time altered and the offset retained.
This method returns an object with the same ZoneOffset
and the specified LocalTime
.
No calculation is needed or performed.
timeProvider
- the local time to change to, not nullOffsetTime
based on this time with the requested time, never nullpublic ZoneOffset getOffset()
public OffsetTime withOffsetSameLocal(ZoneOffset offset)
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
.
To take into account the difference between the offsets, and adjust the time fields,
use withOffsetSameInstant(javax.time.calendar.ZoneOffset)
.
This instance is immutable and unaffected by this method call.
offset
- the zone offset to change to, not nullOffsetTime
based on this time with the requested offset, never nullpublic OffsetTime withOffsetSameInstant(ZoneOffset offset)
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 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
.
To change the offset without adjusting the local time use withOffsetSameLocal(javax.time.calendar.ZoneOffset)
.
This instance is immutable and unaffected by this method call.
offset
- the zone offset to change to, not nullOffsetTime
based on this time with the requested offset, never nullpublic int getHourOfDay()
public int getMinuteOfHour()
public int getSecondOfMinute()
public int getNanoOfSecond()
public OffsetTime with(TimeAdjuster adjuster)
OffsetTime
with the time altered using the adjuster.
Adjusters can be used to alter the time in various ways. 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 end of the working day.
This instance is immutable and unaffected by this method call.
adjuster
- the adjuster to use, not nullOffsetTime
based on this time adjusted as necessary, never nullpublic OffsetTime withHourOfDay(int hourOfDay)
OffsetTime
with the hour-of-day value altered.
This instance is immutable and unaffected by this method call.
hourOfDay
- the hour-of-day to represent, from 0 to 23OffsetTime
based on this time with the requested hour, never nullIllegalCalendarFieldValueException
- if the hour value is invalidpublic OffsetTime withMinuteOfHour(int minuteOfHour)
OffsetTime
with the minute-of-hour value altered.
This instance is immutable and unaffected by this method call.
minuteOfHour
- the minute-of-hour to represent, from 0 to 59OffsetTime
based on this time with the requested minute, never nullIllegalCalendarFieldValueException
- if the minute value is invalidpublic OffsetTime withSecondOfMinute(int secondOfMinute)
OffsetTime
with the second-of-minute value altered.
This instance is immutable and unaffected by this method call.
secondOfMinute
- the second-of-minute to represent, from 0 to 59OffsetTime
based on this time with the requested second, never nullIllegalCalendarFieldValueException
- if the second value is invalidpublic OffsetTime withNanoOfSecond(int nanoOfSecond)
OffsetTime
with the nano-of-second value altered.
This instance is immutable and unaffected by this method call.
nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999OffsetTime
based on this time with the requested nanosecond, never nullIllegalCalendarFieldValueException
- if the nanos value is invalidpublic OffsetTime plus(PeriodProvider periodProvider)
OffsetTime
with the specified period added.
This adds the specified period to this time, returning a new time. The calculation wraps around midnight and ignores any date-based ISO fields.
The period is interpreted using rules equivalent to Period.ofTimeFields(PeriodProvider)
.
Those rules ignore any date-based ISO fields, thus adding a date-based
period to this time will have no effect.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to add, not nullOffsetTime
based on this time with the period added, never nullCalendricalException
- if the specified period cannot be converted to a Period
ArithmeticException
- if the period overflows during conversion to hours/minutes/seconds/nanospublic OffsetTime plus(Duration duration)
OffsetTime
with the specified duration added.
This adds the specified duration to this time, returning a new time. The calculation wraps around midnight.
The calculation is equivalent to using plusSeconds(long)
and
plusNanos(long)
on the two parts of the duration.
This instance is immutable and unaffected by this method call.
duration
- the duration to add, not nullOffsetTime
based on this time with the duration added, never nullpublic OffsetTime plusHours(long hours)
OffsetTime
with the specified period in hours added.
This adds the specified number of hours to this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
hours
- the hours to add, may be negativeOffsetTime
based on this time with the hours added, never nullpublic OffsetTime plusMinutes(long minutes)
OffsetTime
with the specified period in minutes added.
This adds the specified number of minutes to this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to add, may be negativeOffsetTime
based on this time with the minutes added, never nullpublic OffsetTime plusSeconds(long seconds)
OffsetTime
with the specified period in seconds added.
This adds the specified number of seconds to this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to add, may be negativeOffsetTime
based on this time with the seconds added, never nullpublic OffsetTime plusNanos(long nanos)
OffsetTime
with the specified period in nanoseconds added.
This adds the specified number of nanoseconds to this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to add, may be negativeOffsetTime
based on this time with the nanoseconds added, never nullpublic OffsetTime minus(PeriodProvider periodProvider)
OffsetTime
with the specified period subtracted.
This subtracts the specified period from this time, returning a new time. The calculation wraps around midnight and ignores any date-based ISO fields.
The period is interpreted using rules equivalent to Period.ofTimeFields(PeriodProvider)
.
Those rules ignore any date-based ISO fields, thus adding a date-based
period to this time will have no effect.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to subtract, not nullOffsetTime
based on this time with the period subtracted, never nullCalendricalException
- if the specified period cannot be converted to a Period
ArithmeticException
- if the period overflows during conversion to hours/minutes/seconds/nanospublic OffsetTime minus(Duration duration)
OffsetTime
with the specified duration subtracted.
This subtracts the specified duration to this time, returning a new time. The calculation wraps around midnight.
The calculation is equivalent to using minusSeconds(long)
and
minusNanos(long)
on the two parts of the duration.
This instance is immutable and unaffected by this method call.
duration
- the duration to subtract, not nullOffsetTime
based on this time with the duration subtracted, never nullpublic OffsetTime minusHours(long hours)
OffsetTime
with the specified period in hours subtracted.
This subtracts the specified number of hours from this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
hours
- the hours to subtract, may be negativeOffsetTime
based on this time with the hours subtracted, never nullpublic OffsetTime minusMinutes(long minutes)
OffsetTime
with the specified period in minutes subtracted.
This subtracts the specified number of minutes from this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to subtract, may be negativeOffsetTime
based on this time with the minutes subtracted, never nullpublic OffsetTime minusSeconds(long seconds)
OffsetTime
with the specified period in seconds subtracted.
This subtracts the specified number of seconds from this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to subtract, may be negativeOffsetTime
based on this time with the seconds subtracted, never nullpublic OffsetTime minusNanos(long nanos)
OffsetTime
with the specified period in nanoseconds subtracted.
This subtracts the specified number of nanoseconds from this time, returning a new time. The calculation wraps around midnight.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to subtract, may be negativeOffsetTime
based on this time with the nanoseconds subtracted, never nullpublic boolean matches(CalendricalMatcher matcher)
OffsetTime
matches the specified matcher.
Matchers can be used to query the time. A simple matcher might simply compare one of the fields, such as the hour field. A more complex matcher might check if the time is the last second of the day.
matcher
- the matcher to use, not nullpublic boolean matchesCalendrical(Calendrical calendrical)
This method implements the CalendricalMatcher
interface.
It is intended that applications use matches(javax.time.calendar.CalendricalMatcher)
rather than this method.
matchesCalendrical
in interface CalendricalMatcher
calendrical
- the calendrical to match, not nullpublic LocalTime adjustTime(LocalTime time)
This method implements the TimeAdjuster
interface.
It is intended that applications use with(TimeAdjuster)
rather than this method.
adjustTime
in interface TimeAdjuster
time
- the time to be adjusted, not nullpublic LocalTime toLocalTime()
LocalTime
.toLocalTime
in interface TimeProvider
public int compareTo(OffsetTime other)
OffsetTime
to another time based on the UTC equivalent times
then local time.
This ordering is consistent with equals()
.
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
equals()
.compareTo
in interface Comparable<OffsetTime>
other
- the other time to compare to, not nullNullPointerException
- if other
is nullpublic boolean isAfter(OffsetTime other)
OffsetTime
is after that of the
specified time applying both times to a common date.
This method differs from the comparison in compareTo(javax.time.calendar.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.
other
- the other time to compare to, not nullpublic boolean isBefore(OffsetTime other)
OffsetTime
is before that of the
specified time applying both times to a common date.
This method differs from the comparison in compareTo(javax.time.calendar.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.
other
- the other time to compare to, not nullpublic boolean equalInstant(OffsetTime other)
OffsetTime
is equal to that of the
specified time applying both times to a common date.
This method differs from the comparison in compareTo(javax.time.calendar.OffsetTime)
and equals(java.lang.Object)
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.
other
- the other time to compare to, not nullpublic boolean equals(Object other)
OffsetTime
is equal to the specified time.
The comparison is based on the time and the offset.
public int hashCode()
OffsetTime
.public String toString()
String
, such as 10:15:30+01:00
.
The output will be one of the following formats:
HH:mmZZZZ
HH:mm:ssZZZZ
HH:mm:ssfnnnZZZZ
HH:mm:ssfnnnnnnZZZZ
HH:mm:ssfnnnnnnnnnZZZZ
public String toString(DateTimeFormatter formatter)
String
using the formatter.formatter
- the formatter to use, not nullUnsupportedOperationException
- if the formatter cannot printCalendricalPrintException
- if an error occurs during printingpublic static CalendricalRule<OffsetTime> rule()
OffsetTime
.Copyright © 2014. All rights reserved.