|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.time.calendar.OffsetTime
public final class OffsetTime
A time with a zone offset from UTC in the ISO-8601 calendar system,
such as 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.
For example, the value "13:45.30.123456789+02:00" can be stored
in a OffsetTime
.
OffsetTime is immutable and thread-safe.
Method Summary | ||
---|---|---|
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(java.lang.Object obj)
Checks if this time is equal to another time. |
|
static OffsetTime |
from(Calendrical... calendricals)
Obtains an instance of OffsetTime from a set of calendricals. |
|
|
get(CalendricalRule<T> ruleToDerive)
Gets the value of the specified calendrical rule. |
|
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 time. |
|
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(LocalTime time,
ZoneOffset offset)
Obtains an instance of OffsetTime from a local time and an offset. |
|
static OffsetTime |
ofInstant(InstantProvider instantProvider,
ZoneOffset offset)
Obtains an instance of OffsetTime from an InstantProvider . |
|
static OffsetTime |
ofInstantUTC(InstantProvider instantProvider)
Obtains an instance of OffsetTime from an InstantProvider
using the UTC offset. |
|
static OffsetTime |
parse(java.lang.CharSequence text)
Obtains an instance of OffsetTime from a text string such as 10:15:30+01:00 . |
|
static OffsetTime |
parse(java.lang.CharSequence 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 . |
|
java.lang.String |
toString()
Outputs this time as a String , such as 10:15:30+01:00 . |
|
java.lang.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. |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Method Detail |
---|
public static CalendricalRule<OffsetTime> rule()
OffsetTime
.
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 null
public 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 null
IllegalCalendarFieldValueException
- 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 null
IllegalCalendarFieldValueException
- 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 null
IllegalCalendarFieldValueException
- if the value of any field is out of rangepublic static OffsetTime of(LocalTime time, ZoneOffset offset)
OffsetTime
from a local time and an offset.
time
- the local time, not nulloffset
- the zone offset, not null
public static OffsetTime ofInstantUTC(InstantProvider instantProvider)
OffsetTime
from an InstantProvider
using the UTC offset.
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 null
public 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 null
public static OffsetTime from(Calendrical... calendricals)
OffsetTime
from a set of calendricals.
A calendrical represents some form of date and time information. This method combines the input calendricals into a time.
calendricals
- the calendricals to create a time from, no nulls, not null
CalendricalException
- if unable to merge to an offset timepublic static OffsetTime parse(java.lang.CharSequence text)
OffsetTime
from a text string such as 10:15:30+01:00
.
The string must represent a valid time and is parsed using
DateTimeFormatters.isoOffsetTime()
.
Hour, minute and offset are required.
Seconds and fractional seconds are optional.
text
- the text to parse such as "10:15:30+01:00", not null
CalendricalParseException
- if the text cannot be parsedpublic static OffsetTime parse(java.lang.CharSequence 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 null
java.lang.UnsupportedOperationException
- if the formatter cannot parse
CalendricalParseException
- if the text cannot be parsedpublic <T> T get(CalendricalRule<T> ruleToDerive)
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
ruleToDerive
- the rule to derive, not null
public 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 null
OffsetTime
based on this time with the requested offset, not 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 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 null
OffsetTime
based on this time with the requested offset, not 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.
This adjusts the time according to the rules of the specified adjuster.
The offset is not part of the calculation and will be unchanged in the result.
Note that LocalTime
implements TimeAdjuster
, thus this method
can be used to change the entire time.
This instance is immutable and unaffected by this method call.
adjuster
- the adjuster to use, not null
OffsetTime
based on this time adjusted as necessary, not 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 23
OffsetTime
based on this time with the requested hour, not null
IllegalCalendarFieldValueException
- 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 59
OffsetTime
based on this time with the requested minute, not null
IllegalCalendarFieldValueException
- 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 59
OffsetTime
based on this time with the requested second, not null
IllegalCalendarFieldValueException
- 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,999
OffsetTime
based on this time with the requested nanosecond, not null
IllegalCalendarFieldValueException
- 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 null
OffsetTime
based on this time with the period added, not null
CalendricalException
- if the specified period cannot be converted to a Period
java.lang.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 null
OffsetTime
based on this time with the duration added, not 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 negative
OffsetTime
based on this time with the hours added, not 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 negative
OffsetTime
based on this time with the minutes added, not 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 negative
OffsetTime
based on this time with the seconds added, not 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 negative
OffsetTime
based on this time with the nanoseconds added, not 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 null
OffsetTime
based on this time with the period subtracted, not null
CalendricalException
- if the specified period cannot be converted to a Period
java.lang.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 null
OffsetTime
based on this time with the duration subtracted, not 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 negative
OffsetTime
based on this time with the hours subtracted, not 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 negative
OffsetTime
based on this time with the minutes subtracted, not 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 negative
OffsetTime
based on this time with the seconds subtracted, not 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 negative
OffsetTime
based on this time with the nanoseconds subtracted, not 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 null
public 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 null
public LocalTime toLocalTime()
LocalTime
.
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 java.lang.Comparable<OffsetTime>
other
- the other time to compare to, not null
java.lang.NullPointerException
- 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 null
public 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 null
public 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 null
public boolean equals(java.lang.Object obj)
The comparison is based on the local-time and the offset.
To compare for the same instant on the time-line, use equalInstant(javax.time.calendar.OffsetTime)
.
equals
in class java.lang.Object
obj
- the object to check, null returns false
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
String
, such as 10:15:30+01:00
.
The output will be one of the following ISO-8601 formats:
HH:mmXXXXX
HH:mm:ssXXXXX
HH:mm:ssfnnnXXXXX
HH:mm:ssfnnnnnnXXXXX
HH:mm:ssfnnnnnnnnnXXXXX
toString
in class java.lang.Object
public java.lang.String toString(DateTimeFormatter formatter)
String
using the formatter.
formatter
- the formatter to use, not null
java.lang.UnsupportedOperationException
- if the formatter cannot print
CalendricalException
- if an error occurs during printing
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |