public final class ZonedDateTime extends Object implements InstantProvider, DateTimeProvider, Calendrical, CalendricalMatcher, Comparable<ZonedDateTime>, Serializable
2007-12-03T10:15:30+01:00 Europe/Paris
.
ZonedDateTime
is an immutable representation of a date-time with a time-zone.
This class stores all date and time fields, to a precision of nanoseconds,
as well as a time-zone and zone offset. Thus, for example, the value
"2nd October 2007 at 13:45.30.123456789 +02:00 in the Europe/Paris time-zone"
can be stored in a ZonedDateTime
.
The purpose of storing the time-zone is to distinguish the ambiguous case where the local time-line overlaps, typically as a result of the end of daylight time. Information about the local-time can be obtained using methods on the time-zone.
This class provides control over what happens at these cutover points
(typically a gap in spring and an overlap in autumn). The ZoneResolver
interface and implementations in ZoneResolvers
provide strategies for
handling these cases. The methods withEarlierOffsetAtOverlap()
and
withLaterOffsetAtOverlap()
provide further control for overlaps.
ZonedDateTime is immutable and thread-safe.
Modifier and Type | Method and Description |
---|---|
int |
compareTo(ZonedDateTime other)
Compares this
ZonedDateTime to another date-time based on the UTC
equivalent date-times then time-zone unique key. |
boolean |
equalInstant(ZonedDateTime other)
Checks if the instant of this date-time is equal to that of the specified date-time.
|
boolean |
equals(Object other)
Checks if this
ZonedDateTime is equal to the specified date-time. |
<T> T |
get(CalendricalRule<T> rule)
Gets the value of the specified calendrical rule.
|
ZoneRules |
getApplicableRules()
Calculates the zone rules applicable for this date-time.
|
TimeZone |
getApplicableZone()
Calculates the applicable versioned time-zone, such as 'Europe/Paris#2009b'.
|
ISOChronology |
getChronology()
Gets the chronology that this date-time uses, which is the ISO calendar system.
|
int |
getDayOfMonth()
Gets the day-of-month field.
|
DayOfWeek |
getDayOfWeek()
Gets the day-of-week field, which is an enum
DayOfWeek . |
int |
getDayOfYear()
Gets the day-of-year field.
|
int |
getHourOfDay()
Gets the hour-of-day field.
|
int |
getMinuteOfHour()
Gets the minute-of-hour field.
|
MonthOfYear |
getMonthOfYear()
Gets the month-of-year field, which is an enum
MonthOfYear . |
int |
getNanoOfSecond()
Gets the nano-of-second field.
|
ZoneOffset |
getOffset()
Gets the zone offset, such as '+01:00'.
|
int |
getSecondOfMinute()
Gets the second-of-minute field.
|
int |
getYear()
Gets the year field.
|
TimeZone |
getZone()
Gets the time-zone, such as 'Europe/Paris'.
|
int |
hashCode()
A hash code for this
ZonedDateTime . |
boolean |
isAfter(ZonedDateTime other)
Checks if the instant of this date-time is after that of the specified date-time.
|
boolean |
isBefore(ZonedDateTime other)
Checks if the instant of this date-time is before that of the specified date-time.
|
boolean |
isLeapYear()
Checks if the year is a leap year, according to the ISO proleptic
calendar system rules.
|
boolean |
matches(CalendricalMatcher matcher)
Checks whether this
ZonedDateTime matches the specified matcher. |
boolean |
matchesCalendrical(Calendrical calendrical)
Checks if the date-time extracted from the calendrical matches this.
|
ZonedDateTime |
minus(PeriodProvider periodProvider)
Returns a copy of this
ZonedDateTime with the specified period subtracted. |
ZonedDateTime |
minus(PeriodProvider periodProvider,
ZoneResolver resolver)
Returns a copy of this
ZonedDateTime with the specified period subtracted. |
ZonedDateTime |
minusDays(long days)
Returns a copy of this
ZonedDateTime with the specified period in days subtracted. |
ZonedDateTime |
minusDuration(Duration duration)
Returns a copy of this
ZonedDateTime with the specified duration subtracted. |
ZonedDateTime |
minusDuration(int hours,
int minutes,
int seconds,
long nanos)
Returns a copy of this
ZonedDateTime with the specified duration subtracted. |
ZonedDateTime |
minusDuration(PeriodProvider periodProvider)
Returns a copy of this
ZonedDateTime with the specified duration subtracted. |
ZonedDateTime |
minusHours(long hours)
Returns a copy of this
ZonedDateTime with the specified period in hours subtracted. |
ZonedDateTime |
minusMinutes(long minutes)
Returns a copy of this
ZonedDateTime with the specified period in minutes subtracted. |
ZonedDateTime |
minusMonths(long months)
Returns a copy of this
ZonedDateTime with the specified period in months subtracted. |
ZonedDateTime |
minusNanos(long nanos)
Returns a copy of this
ZonedDateTime with the specified period in nanoseconds subtracted. |
ZonedDateTime |
minusSeconds(long seconds)
Returns a copy of this
ZonedDateTime with the specified period in seconds subtracted. |
ZonedDateTime |
minusWeeks(long weeks)
Returns a copy of this
ZonedDateTime with the specified period in weeks subtracted. |
ZonedDateTime |
minusYears(long years)
Returns a copy of this
ZonedDateTime with the specified period in years subtracted. |
static ZonedDateTime |
now()
Obtains the current date-time from the system clock in the default time-zone.
|
static ZonedDateTime |
now(Clock clock)
Obtains the current date-time from the specified clock.
|
static ZonedDateTime |
of(DateProvider dateProvider,
TimeProvider timeProvider,
TimeZone zone)
Obtains an instance of
ZonedDateTime from a local date and time
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(DateProvider dateProvider,
TimeProvider timeProvider,
TimeZone zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from a local date and time
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(DateTimeProvider dateTimeProvider,
TimeZone zone)
Obtains an instance of
ZonedDateTime from a local date-time
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(DateTimeProvider dateTimeProvider,
TimeZone zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from a local date-time
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(int year,
int monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int nanoOfSecond,
TimeZone zone)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(int year,
int monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int nanoOfSecond,
TimeZone zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(int year,
MonthOfYear monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int nanoOfSecond,
TimeZone zone)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(int year,
MonthOfYear monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int nanoOfSecond,
TimeZone zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(OffsetDateTime dateTime,
TimeZone zone)
Obtains an instance of
ZonedDateTime from an OffsetDateTime
ensuring that the offset provided is valid for the time-zone. |
static ZonedDateTime |
ofEpochSeconds(long epochSeconds,
TimeZone zone)
Obtains an instance of
ZonedDateTime using seconds from the
epoch of 1970-01-01T00:00:00Z. |
static ZonedDateTime |
ofInstant(InstantProvider instantProvider,
TimeZone zone)
Obtains an instance of
ZonedDateTime from an Instant . |
static ZonedDateTime |
ofInstant(OffsetDateTime dateTime,
TimeZone zone)
Obtains an instance of
ZonedDateTime from the instant of an OffsetDateTime . |
static ZonedDateTime |
parse(String text)
Obtains an instance of
ZonedDateTime from a text string such as
2007-12-03T10:15:30+01:00[Europe/Paris] . |
static ZonedDateTime |
parse(String text,
DateTimeFormatter formatter)
Obtains an instance of
ZonedDateTime from a text string using a specific formatter. |
ZonedDateTime |
plus(PeriodProvider periodProvider)
Returns a copy of this
ZonedDateTime with the specified period added. |
ZonedDateTime |
plus(PeriodProvider periodProvider,
ZoneResolver resolver)
Returns a copy of this
ZonedDateTime with the specified period added. |
ZonedDateTime |
plusDays(long days)
Returns a copy of this
ZonedDateTime with the specified period in days added. |
ZonedDateTime |
plusDuration(Duration duration)
Returns a copy of this
ZonedDateTime with the specified duration added. |
ZonedDateTime |
plusDuration(int hours,
int minutes,
int seconds,
long nanos)
Returns a copy of this
ZonedDateTime with the specified duration added. |
ZonedDateTime |
plusDuration(PeriodProvider periodProvider)
Returns a copy of this
ZonedDateTime with the specified duration added. |
ZonedDateTime |
plusHours(long hours)
Returns a copy of this
ZonedDateTime with the specified period in hours added. |
ZonedDateTime |
plusMinutes(long minutes)
Returns a copy of this
ZonedDateTime with the specified period in minutes added. |
ZonedDateTime |
plusMonths(long months)
Returns a copy of this
ZonedDateTime with the specified period in months added. |
ZonedDateTime |
plusNanos(long nanos)
Returns a copy of this
ZonedDateTime with the specified period in nanoseconds added. |
ZonedDateTime |
plusSeconds(long seconds)
Returns a copy of this
ZonedDateTime with the specified period in seconds added. |
ZonedDateTime |
plusWeeks(long weeks)
Returns a copy of this
ZonedDateTime with the specified period in weeks added. |
ZonedDateTime |
plusYears(long years)
Returns a copy of this
ZonedDateTime with the specified period in years added. |
static CalendricalRule<ZonedDateTime> |
rule()
Gets the rule for
ZonedDateTime . |
long |
toEpochSeconds()
Converts this
ZonedDateTime to the number of seconds from the epoch
of 1970-01-01T00:00:00Z. |
Instant |
toInstant()
Converts this
ZonedDateTime to an Instant . |
LocalDate |
toLocalDate()
Converts this
ZonedDateTime to a LocalDate . |
LocalDateTime |
toLocalDateTime()
Converts this
ZonedDateTime to a LocalDateTime . |
LocalTime |
toLocalTime()
Converts this
ZonedDateTime to a LocalTime . |
OffsetDate |
toOffsetDate()
Converts this
ZonedDateTime to a OffsetDate . |
OffsetDateTime |
toOffsetDateTime()
Converts this
ZonedDateTime to a OffsetDateTime . |
OffsetTime |
toOffsetTime()
Converts this
ZonedDateTime to a OffsetTime . |
String |
toString()
Outputs this date-time as a
String , such as
2007-12-03T10:15:30+01:00[Europe/Paris] . |
String |
toString(DateTimeFormatter formatter)
Outputs this date-time as a
String using the formatter. |
ZonedDateTime |
with(DateAdjuster adjuster)
Returns a copy of this
ZonedDateTime with the date altered using the adjuster. |
ZonedDateTime |
with(DateAdjuster adjuster,
ZoneResolver resolver)
Returns a copy of this
ZonedDateTime with the date altered using the
adjuster, providing a resolver to handle an invalid date-time. |
ZonedDateTime |
with(TimeAdjuster adjuster)
Returns a copy of this
ZonedDateTime with the time altered using the adjuster. |
ZonedDateTime |
with(TimeAdjuster adjuster,
ZoneResolver resolver)
Returns a copy of this
ZonedDateTime with the time altered using the
adjuster, providing a resolver to handle an invalid date-time. |
ZonedDateTime |
withDate(int year,
int monthOfYear,
int dayOfMonth)
Returns a copy of this
ZonedDateTime with the date values altered. |
ZonedDateTime |
withDateTime(DateTimeProvider dateTimeProvider)
Returns a copy of this ZonedDateTime with a different local date-time.
|
ZonedDateTime |
withDayOfMonth(int dayOfMonth)
Returns a copy of this
ZonedDateTime with the day-of-month value altered. |
ZonedDateTime |
withDayOfYear(int dayOfYear)
Returns a copy of this
ZonedDateTime with the day-of-year altered. |
ZonedDateTime |
withEarlierOffsetAtOverlap()
Returns a copy of this ZonedDateTime changing the zone offset to the
earlier of the two valid offsets at a local time-line overlap.
|
ZonedDateTime |
withHourOfDay(int hourOfDay)
Returns a copy of this
ZonedDateTime with the hour-of-day value altered. |
ZonedDateTime |
withLaterOffsetAtOverlap()
Returns a copy of this ZonedDateTime changing the zone offset to the
later of the two valid offsets at a local time-line overlap.
|
ZonedDateTime |
withMinuteOfHour(int minuteOfHour)
Returns a copy of this
ZonedDateTime with the minute-of-hour value altered. |
ZonedDateTime |
withMonthOfYear(int monthOfYear)
Returns a copy of this
ZonedDateTime with the month-of-year value altered. |
ZonedDateTime |
withNanoOfSecond(int nanoOfSecond)
Returns a copy of this
ZonedDateTime with the nano-of-second value altered. |
ZonedDateTime |
withSecondOfMinute(int secondOfMinute)
Returns a copy of this
ZonedDateTime with the second-of-minute value altered. |
ZonedDateTime |
withTime(int hourOfDay,
int minuteOfHour)
Returns a copy of this
ZonedDateTime with the time values altered. |
ZonedDateTime |
withTime(int hourOfDay,
int minuteOfHour,
int secondOfMinute)
Returns a copy of this
ZonedDateTime with the time values altered. |
ZonedDateTime |
withTime(int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int nanoOfSecond)
Returns a copy of this
ZonedDateTime with the time values altered. |
ZonedDateTime |
withYear(int year)
Returns a copy of this
ZonedDateTime with the year value altered. |
ZonedDateTime |
withZoneSameInstant(TimeZone zone)
Returns a copy of this ZonedDateTime with a different time-zone,
retaining the instant.
|
ZonedDateTime |
withZoneSameLocal(TimeZone zone)
Returns a copy of this ZonedDateTime with a different time-zone,
retaining the local date-time if possible.
|
ZonedDateTime |
withZoneSameLocal(TimeZone zone,
ZoneResolver resolver)
Returns a copy of this ZonedDateTime with a different time-zone,
retaining the local date-time if possible.
|
public static ZonedDateTime now()
This will query the system clock
in the default
time-zone to obtain the current date-time.
The zone and offset will be set based on 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 ZonedDateTime now(Clock clock)
This will query the specified clock to obtain the current time. The zone and offset will be set based on 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 ZonedDateTime of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone.
The day must be valid for the year and month or an exception will be thrown.
The local date-time must be valid for the time-zone. If the time is invalid for the zone, due to either being a gap or an overlap, then an exception will be thrown.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- 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,999zone
- the time-zone, not nullIllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-yearCalendricalException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone, ZoneResolver resolver)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time.
The day must be valid for the year and month or an exception will be thrown.
The local date-time must be valid for the time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- 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,999zone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullIllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-yearCalendricalException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone.
The day must be valid for the year and month or an exception will be thrown.
The local date-time must be valid for the time-zone. If the time is invalid for the zone, due to either being a gap or an overlap, then an exception will be thrown.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- 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,999zone
- the time-zone, not nullIllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-yearCalendricalException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone, ZoneResolver resolver)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time.
The day must be valid for the year and month or an exception will be thrown.
The local date-time must be valid for the time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hourOfDay
- 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,999zone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullIllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month-yearCalendricalException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(DateProvider dateProvider, TimeProvider timeProvider, TimeZone zone)
ZonedDateTime
from a local date and time
where the date-time must be valid for the time-zone.
This factory creates a ZonedDateTime
from a date, time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then an exception will be thrown.
dateProvider
- the date provider to use, not nulltimeProvider
- the time provider to use, not nullzone
- the time-zone, not nullCalendricalException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(DateProvider dateProvider, TimeProvider timeProvider, TimeZone zone, ZoneResolver resolver)
ZonedDateTime
from a local date and time
providing a resolver to handle an invalid date-time.
This factory creates a ZonedDateTime
from a date, time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
dateProvider
- the date provider to use, not nulltimeProvider
- the time provider to use, not nullzone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullCalendricalException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(DateTimeProvider dateTimeProvider, TimeZone zone)
ZonedDateTime
from a local date-time
where the date-time must be valid for the time-zone.
This factory creates a ZonedDateTime
from a date-time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then an exception will be thrown.
dateTimeProvider
- the date-time provider to use, not nullzone
- the time-zone, not nullCalendricalException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(DateTimeProvider dateTimeProvider, TimeZone zone, ZoneResolver resolver)
ZonedDateTime
from a local date-time
providing a resolver to handle an invalid date-time.
This factory creates a ZonedDateTime
from a date-time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
dateTimeProvider
- the date-time provider to use, not nullzone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullCalendricalException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(OffsetDateTime dateTime, TimeZone zone)
ZonedDateTime
from an OffsetDateTime
ensuring that the offset provided is valid for the time-zone.
This factory creates a ZonedDateTime
from an offset date-time and time-zone.
If the date-time is invalid for the zone due to a time-line gap then an exception is thrown.
Otherwise, the offset is checked against the zone to ensure it is valid.
If the time-zone has a floating version, then this conversion will use the latest time-zone rules that are valid for the input date-time.
An alternative to this method is ofInstant(OffsetDateTime, TimeZone)
.
This method will retain the date and time and throw an exception if
the offset is invalid. The fromInstant
method will change the
date and time if necessary to retain the same instant.
dateTime
- the offset date-time to use, not nullzone
- the time-zone, not nullCalendricalException
- if no rules can be found for the zoneCalendricalException
- if the date-time is invalid due to a gap in the local time-lineCalendricalException
- if the offset is invalid for the time-zone at the date-timepublic static ZonedDateTime ofInstant(InstantProvider instantProvider, TimeZone zone)
ZonedDateTime
from an Instant
.
This factory creates a ZonedDateTime
from an instant and time-zone.
If the instant represents a point on the time-line outside the supported year
range then an exception will be thrown.
If the time-zone has a floating version, then this conversion will use the latest time-zone rules.
instantProvider
- the instant to convert, not nullzone
- the time-zone, not nullCalendricalException
- if the result exceeds the supported rangepublic static ZonedDateTime ofInstant(OffsetDateTime dateTime, TimeZone zone)
ZonedDateTime
from the instant of an OffsetDateTime
.
This factory creates a ZonedDateTime
from an offset date-time and time-zone.
This is an optimized implementation of:
ZonedDateTime.ofInstant(offsetDateTime.toInstant(), zone);If the offset date-time is in the wrong offset for the zone at the gap, then the date, time and offset will be adjusted to ensure that the result has the same instant.
If the time-zone has a floating version, then this conversion will use the latest time-zone rules.
An alternative to this method is of(OffsetDateTime, TimeZone)
.
The fromInstant
method will change the date and time if necessary to
retain the same instant. The dateTime
method will retain the date and
time and throw an exception if the offset is invalid.
dateTime
- the offset date-time to use, not nullzone
- the time-zone, not nullCalendricalException
- if the result exceeds the supported rangepublic static ZonedDateTime ofEpochSeconds(long epochSeconds, TimeZone zone)
ZonedDateTime
using seconds from the
epoch of 1970-01-01T00:00:00Z.
The nanosecond field is set to zero.
epochSeconds
- the number of seconds from the epoch of 1970-01-01T00:00:00Zzone
- the time-zone, not nullCalendricalException
- if the result exceeds the supported rangepublic static ZonedDateTime parse(String text)
ZonedDateTime
from a text string such as
2007-12-03T10:15:30+01:00[Europe/Paris]
.
The following formats are accepted in ASCII:
{Year}-{MonthOfYear}-{DayOfMonth}T{Hour}:{Minute}{OffsetID}[{ZoneId}]
{Year}-{MonthOfYear}-{DayOfMonth}T{Hour}:{Minute}:{Second}{OffsetID}[{ZoneId}]
{Year}-{MonthOfYear}-{DayOfMonth}T{Hour}:{Minute}:{Second}.{NanosecondFraction}{OffsetID}[{ZoneId}]
The year has between 4 and 10 digits with values from MIN_YEAR to MAX_YEAR. If there are more than 4 digits then the year must be prefixed with the plus symbol. Negative years are allowed, but not negative zero.
The month-of-year has 2 digits with values from 1 to 12.
The day-of-month has 2 digits with values from 1 to 31 appropriate to the month.
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
.
The zone ID is the normalized form as defined in TimeZone.getID()
.
text
- the text to parse such as '2007-12-03T10:15:30+01:00[Europe/Paris]', not nullCalendricalException
- if the text cannot be parsedpublic static ZonedDateTime parse(String text, DateTimeFormatter formatter)
ZonedDateTime
from a text string using a specific formatter.
The text is parsed using the formatter, returning a date-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 date-time then
null
will be returned.
get
in interface Calendrical
rule
- the rule to use, not nullpublic ZonedDateTime withDateTime(DateTimeProvider dateTimeProvider)
This method changes the offset date-time stored to a different one. The local date-time is checked against the zone rules, and the retain offset resolver used if necessary.
dateTimeProvider
- the local date-time to change to, not nullZonedDateTime
based on this date-time with the requested date-time, never nullpublic ZoneOffset getOffset()
public ZonedDateTime withEarlierOffsetAtOverlap()
This method only has any effect when the local time-line overlaps, such as at an autumn daylight savings cutover. In this scenario, there are two valid offsets for the local date-time. Calling this method will return a zoned date-time with the earlier of the two selected.
If this method is called when it is not an overlap, this
is returned.
This instance is immutable and unaffected by this method call.
ZonedDateTime
based on this date-time with the earlier offset, never nullCalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-timepublic ZonedDateTime withLaterOffsetAtOverlap()
This method only has any effect when the local time-line overlaps, such as at an autumn daylight savings cutover. In this scenario, there are two valid offsets for the local date-time. Calling this method will return a zoned date-time with the later of the two selected.
If this method is called when it is not an overlap, this
is returned.
This instance is immutable and unaffected by this method call.
ZonedDateTime
based on this date-time with the later offset, never nullCalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-timepublic TimeZone getZone()
The time-zone stored by this ZonedDateTime
can have either a
fixed or a floating version. This method returns the time-zone with
a version, calculating the best matching version if necessary.
This returns the stored time-zone id used to determine the time-zone rules.
A time-zone can have either a fixed or a floating version, where floating
represents the latest version of the underlying rules.
The getApplicableZone()
method will resolve the zone to a specific version.
The getApplicableRules()
method will resolve the actual zone-rules.
public ZonedDateTime withZoneSameLocal(TimeZone zone)
This method changes the time-zone and retains the local date-time.
The local date-time is only changed if it is invalid for the new zone.
In that case, the retain offset
resolver is used.
To change the zone and adjust the local date-time,
use withZoneSameInstant(TimeZone)
.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to change to, not nullZonedDateTime
based on this date-time with the requested zone, never nullpublic ZonedDateTime withZoneSameLocal(TimeZone zone, ZoneResolver resolver)
This method changes the time-zone and retains the local date-time. The local date-time is only changed if it is invalid for the new zone. In that case, the specified resolver is used.
To change the zone and adjust the local date-time,
use withZoneSameInstant(TimeZone)
.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to change to, not nullresolver
- the resolver to use, not nullZonedDateTime
based on this date-time with the requested zone, never nullpublic ZonedDateTime withZoneSameInstant(TimeZone zone)
This method changes the time-zone and retains the instant. This normally results in a change to the local date-time.
This method is based on retaining the same instant, thus gaps and overlaps in the local time-line have no effect on the result.
To change the offset while keeping the local time,
use withZoneSameLocal(TimeZone)
.
zone
- the time-zone to change to, not nullZonedDateTime
based on this date-time with the requested zone, never nullCalendarConversionException
- if the result exceeds the supported date rangepublic TimeZone getApplicableZone()
The time-zone stored by this ZonedDateTime
can have either a
fixed or a floating version. This method returns the time-zone with
a version, calculating the best matching version if necessary.
For a floating time-zone, the applicable version is the latest version for which the offset date-time contained in this object would be valid. If a new version of the time-zone rules is registered then the result of this method may change.
If this instance is created on one JVM and passed by serialization to another JVM it is possible for the time-zone id to be invalid. If this happens, this method will throw an exception.
CalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-timepublic ZoneRules getApplicableRules()
The rules provide the information on how the zone offset changes over time.
This usually includes historical and future information.
The rules are determined using TimeZone.getRulesValidFor(OffsetDateTime)
which finds the best matching set of rules for this date-time.
If a new version of the time-zone rules is registered then the result
of this method may change.
If this instance is created on one JVM and passed by serialization to another JVM it is possible for the time-zone id to be invalid. If this happens, this method will throw an exception.
CalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-timepublic int getYear()
This method returns the primitive int
value for the year.
Additional information about the year can be obtained by creating a Year
.
public MonthOfYear getMonthOfYear()
MonthOfYear
.
This method returns the enum MonthOfYear
for the month.
This avoids confusion as to what int
values mean.
If you need access to the primitive int
value then the enum
provides the int value
.
Additional information can be obtained from the MonthOfYear
.
This includes month lengths, textual names and access to the quarter-of-year
and month-of-quarter values.
public int getDayOfMonth()
This method returns the primitive int
value for the day-of-month.
public int getDayOfYear()
This method returns the primitive int
value for the day-of-year.
public DayOfWeek getDayOfWeek()
DayOfWeek
.
This method returns the enum DayOfWeek
for the day-of-week.
This avoids confusion as to what int
values mean.
If you need access to the primitive int
value then the enum
provides the int value
.
Additional information can be obtained from the DayOfWeek
.
This includes textual names of the values.
public int getHourOfDay()
public int getMinuteOfHour()
public int getSecondOfMinute()
public int getNanoOfSecond()
public boolean isLeapYear()
This method applies the current rules for leap years across the whole time-line. In general, a year is a leap year if it is divisible by four without remainder. However, years divisible by 100, are not leap years, with the exception of years divisible by 400 which are.
For example, 1904 is a leap year it is divisible by 4. 1900 was not a leap year as it is divisible by 100, however 2000 was a leap year as it is divisible by 400.
The calculation is proleptic - applying the same rules into the far future and far past. This is historically inaccurate, but is correct for the ISO8601 standard.
public ZonedDateTime with(DateAdjuster adjuster)
ZonedDateTime
with the date altered using the adjuster.
Adjusters can be used to alter the date in various ways. A simple adjuster might simply set the one of the fields, such as the year field. A more complex adjuster might set the date to the last day of the month.
If the adjusted date results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
adjuster
- the adjuster to use, not nullZonedDateTime
based on this date-time with the date adjusted, never nullIllegalArgumentException
- if the adjuster returned nullpublic ZonedDateTime with(DateAdjuster adjuster, ZoneResolver resolver)
ZonedDateTime
with the date altered using the
adjuster, providing a resolver to handle an invalid date-time.
Adjusters can be used to alter the date in various ways. A simple adjuster might simply set the one of the fields, such as the year field. A more complex adjuster might set the date to the last day of the month.
This instance is immutable and unaffected by this method call.
adjuster
- the adjuster to use, not nullresolver
- the resolver to use, not nullZonedDateTime
based on this date-time with the date adjusted, never nullIllegalArgumentException
- if the adjuster returned nullIllegalCalendarFieldValueException
- if the resolver cannot resolve the date-timepublic ZonedDateTime with(TimeAdjuster adjuster)
ZonedDateTime
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.
If the adjusted date results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
adjuster
- the adjuster to use, not nullZonedDateTime
based on this date-time with the time adjusted, never nullIllegalArgumentException
- if the adjuster returned nullpublic ZonedDateTime with(TimeAdjuster adjuster, ZoneResolver resolver)
ZonedDateTime
with the time altered using the
adjuster, providing a resolver to handle an invalid date-time.
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 nullresolver
- the resolver to use, not nullZonedDateTime
based on this date-time with the time adjusted, never nullIllegalArgumentException
- if the adjuster returned nullIllegalCalendarFieldValueException
- if the resolver cannot resolve the date-timepublic ZonedDateTime withYear(int year)
ZonedDateTime
with the year value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
year
- the year to represent, from MIN_YEAR to MAX_YEARZonedDateTime
based on this date-time with the requested year, never nullIllegalCalendarFieldValueException
- if the year value is invalidpublic ZonedDateTime withMonthOfYear(int monthOfYear)
ZonedDateTime
with the month-of-year value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
monthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)ZonedDateTime
based on this date-time with the requested month, never nullIllegalCalendarFieldValueException
- if the month value is invalidpublic ZonedDateTime withDayOfMonth(int dayOfMonth)
ZonedDateTime
with the day-of-month value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
dayOfMonth
- the day-of-month to represent, from 1 to 31ZonedDateTime
based on this date-time with the requested day, never nullIllegalCalendarFieldValueException
- if the day-of-month value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month-yearpublic ZonedDateTime withDayOfYear(int dayOfYear)
ZonedDateTime
with the day-of-year altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
dayOfYear
- the day-of-year to set in the returned date, from 1 to 365-366ZonedDateTime
based on this date with the requested day, never nullIllegalCalendarFieldValueException
- if the day-of-year value is invalidInvalidCalendarFieldException
- if the day-of-year is invalid for the yearpublic ZonedDateTime withDate(int year, int monthOfYear, int dayOfMonth)
ZonedDateTime
with the date values altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This method will return a new instance with the same time fields, but altered date fields.
This instance is immutable and unaffected by this method call.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31ZonedDateTime
based on this date-time with the requested date, never nullIllegalCalendarFieldValueException
- if the any field value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month-yearpublic ZonedDateTime withHourOfDay(int hourOfDay)
ZonedDateTime
with the hour-of-day value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hourOfDay
- the hour-of-day to represent, from 0 to 23ZonedDateTime
based on this date-time with the requested hour, never nullIllegalCalendarFieldValueException
- if the hour value is invalidpublic ZonedDateTime withMinuteOfHour(int minuteOfHour)
ZonedDateTime
with the minute-of-hour value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minuteOfHour
- the minute-of-hour to represent, from 0 to 59ZonedDateTime
based on this date-time with the requested minute, never nullIllegalCalendarFieldValueException
- if the minute value is invalidpublic ZonedDateTime withSecondOfMinute(int secondOfMinute)
ZonedDateTime
with the second-of-minute value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
secondOfMinute
- the second-of-minute to represent, from 0 to 59ZonedDateTime
based on this date-time with the requested second, never nullIllegalCalendarFieldValueException
- if the second value is invalidpublic ZonedDateTime withNanoOfSecond(int nanoOfSecond)
ZonedDateTime
with the nano-of-second value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999ZonedDateTime
based on this date-time with the requested nanosecond, never nullIllegalCalendarFieldValueException
- if the nanos value is invalidpublic ZonedDateTime withTime(int hourOfDay, int minuteOfHour)
ZonedDateTime
with the time values altered.
This method will return a new instance with the same date fields,
but altered time fields.
This is a shorthand for withTime(int,int,int)
and sets
the second field to zero.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59ZonedDateTime
based on this date-time with the requested time, never nullIllegalCalendarFieldValueException
- if any field value is invalidpublic ZonedDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
ZonedDateTime
with the time values altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
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 59ZonedDateTime
based on this date-time with the requested time, never nullIllegalCalendarFieldValueException
- if any field value is invalidpublic ZonedDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
ZonedDateTime
with the time values altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
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,999ZonedDateTime
based on this date-time with the requested time, never nullIllegalCalendarFieldValueException
- if any field value is invalidpublic ZonedDateTime plus(PeriodProvider periodProvider)
ZonedDateTime
with the specified period added.
This adds the specified period to this date-time, returning a new date-time.
Before addition, the period is converted to a Period
using the
Period.of(PeriodProvider)
.
The addition occurs based on the local date-time.
After the calculation, the local date-time may be in a gap or overlap.
If so, then the ZoneResolvers.retainOffset()
resolver is used.
The detailed rules for the addition have some complexity due to variable length months.
See LocalDateTime.plus(PeriodProvider)
for details.
See plusDuration(PeriodProvider)
for a similar method that performs
the addition in a different manner, taking into account gaps and overlaps.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to add, not nullZonedDateTime
based on this date-time with the period added, never nullCalendricalException
- if the specified period cannot be converted to a Period
CalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plus(PeriodProvider periodProvider, ZoneResolver resolver)
ZonedDateTime
with the specified period added.
This adds the specified period to this date-time, returning a new date-time.
Before addition, the period is converted to a Period
using the
Period.of(PeriodProvider)
.
The addition occurs based on the local date-time. After the calculation, the local date-time may be in a gap or overlap. If so, then the specified resolver is used.
The detailed rules for the addition have some complexity due to variable length months.
See LocalDateTime.plus(PeriodProvider)
for details.
See plusDuration(PeriodProvider)
for a similar method that performs
the addition in a different manner, taking into account gaps and overlaps.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to add, not nullZonedDateTime
based on this date-time with the period added, never nullCalendricalException
- if the specified period cannot be converted to a Period
CalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusYears(long years)
ZonedDateTime
with the specified period in years added.
This method add the specified amount to the years field in four steps:
ZoneResolvers.retainOffset()
For example, 2008-02-29 (leap year) plus one year would result in the invalid date 2009-02-29 (standard year). Instead of returning an invalid result, the last valid day of the month, 2009-02-28, is selected instead.
This instance is immutable and unaffected by this method call.
years
- the years to add, positive or negativeZonedDateTime
based on this date-time with the years added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusMonths(long months)
ZonedDateTime
with the specified period in months added.
This method adds the specified amount to the months field in four steps:
ZoneResolvers.retainOffset()
For example, 2007-03-31 plus one month would result in the invalid date 2007-04-31. Instead of returning an invalid result, the last valid day of the month, 2007-04-30, is selected instead.
This instance is immutable and unaffected by this method call.
months
- the months to add, positive or negativeZonedDateTime
based on this date-time with the months added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusWeeks(long weeks)
ZonedDateTime
with the specified period in weeks added.
This method adds the specified amount in weeks to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 plus one week would result in the 2009-01-07.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
weeks
- the weeks to add, positive or negativeZonedDateTime
based on this date-time with the weeks added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusDays(long days)
ZonedDateTime
with the specified period in days added.
This method adds the specified amount to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 plus one day would result in the 2009-01-01.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
days
- the days to add, positive or negativeZonedDateTime
based on this date-time with the days added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusHours(long hours)
ZonedDateTime
with the specified period in hours added.
This method uses field based addition. This method changes the field by the specified number of hours. This may, at daylight savings cutover, result in a duration being added that is more or less than the specified number of hours.
For example, consider a time-zone where the spring DST cutover means that the local times 01:00 to 01:59 do not exist. Using this method, adding a period of 2 hours to 00:30 will result in 02:30, but it is important to note that the change in duration was only 1 hour.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hours
- the hours to add, positive or negativeZonedDateTime
based on this date-time with the hours added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusMinutes(long minutes)
ZonedDateTime
with the specified period in minutes added.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to add, positive or negativeZonedDateTime
based on this date-time with the minutes added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusSeconds(long seconds)
ZonedDateTime
with the specified period in seconds added.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to add, positive or negativeZonedDateTime
based on this date-time with the seconds added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusNanos(long nanos)
ZonedDateTime
with the specified period in nanoseconds added.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to add, positive or negativeZonedDateTime
based on this date-time with the nanoseconds added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusDuration(PeriodProvider periodProvider)
ZonedDateTime
with the specified duration added.
This method converts
the period to a duration
based on the ISOChronology
seconds and nanoseconds units.
The duration is then added to the instant
equivalent of this instance.
Adding a duration differs from adding a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then adding a duration of one hour to 00:30 will yield 02:30.
The addition of a duration is always absolute and zone-resolvers are not required.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to add, positive or negativeZonedDateTime
based on this date-time with the duration added, never nullArithmeticException
- if the calculation exceeds the capacity of Instant
CalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusDuration(Duration duration)
ZonedDateTime
with the specified duration added.
This adds the specified duration to this date-time, returning a new date-time.
The calculation is equivalent to addition on the instant
equivalent of this instance.
Adding a duration differs from adding a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then adding a duration of one hour to 00:30 will yield 02:30.
This instance is immutable and unaffected by this method call.
duration
- the duration to add, not nullZonedDateTime
based on this date-time with the duration added, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime plusDuration(int hours, int minutes, int seconds, long nanos)
ZonedDateTime
with the specified duration added.
Adding a duration differs from adding a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then adding a duration of one hour to 00:30 will yield 02:30.
The addition of a duration is always absolute and zone-resolvers are not required.
This instance is immutable and unaffected by this method call.
hours
- the hours to add, positive or negativeminutes
- the minutes to add, positive or negativeseconds
- the seconds to add, positive or negativenanos
- the nanos to add, positive or negativeZonedDateTime
based on this date-time with the duration added, never nullArithmeticException
- if the calculation exceeds the capacity of Instant
CalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minus(PeriodProvider periodProvider)
ZonedDateTime
with the specified period subtracted.
This subtracts the specified period from this date-time, returning a new date-time.
Before subtraction, the period is converted to a Period
using the
Period.of(PeriodProvider)
.
The subtraction occurs based on the local date-time.
After the calculation, the local date-time may be in a gap or overlap.
If so, then the ZoneResolvers.retainOffset()
resolver is used.
The detailed rules for the subtraction have some complexity due to variable length months.
See LocalDateTime.minus(PeriodProvider)
for details.
See minusDuration(PeriodProvider)
for a similar method that performs
the subtraction in a different manner, taking into account gaps and overlaps.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to subtract, not nullZonedDateTime
based on this date-time with the period subtracted, never nullCalendricalException
- if the specified period cannot be converted to a Period
CalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minus(PeriodProvider periodProvider, ZoneResolver resolver)
ZonedDateTime
with the specified period subtracted.
This subtracts the specified period from this date-time, returning a new date-time.
Before subtraction, the period is converted to a Period
using the
Period.of(PeriodProvider)
.
The subtraction occurs based on the local date-time. After the calculation, the local date-time may be in a gap or overlap. If so, then the specified resolver is used.
The detailed rules for the subtraction have some complexity due to variable length months.
See LocalDateTime.minus(PeriodProvider)
for details.
See minusDuration(PeriodProvider)
for a similar method that performs
the subtraction in a different manner, taking into account gaps and overlaps.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to subtract, not nullZonedDateTime
based on this date-time with the period subtracted, never nullCalendricalException
- if the specified period cannot be converted to a Period
CalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusYears(long years)
ZonedDateTime
with the specified period in years subtracted.
This method subtracts the specified amount to the years field in four steps:
ZoneResolvers.retainOffset()
For example, 2008-02-29 (leap year) minus one year would result in the invalid date 2009-02-29 (standard year). Instead of returning an invalid result, the last valid day of the month, 2009-02-28, is selected instead.
This instance is immutable and unaffected by this method call.
years
- the years to subtract, positive or negativeZonedDateTime
based on this date-time with the years subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusMonths(long months)
ZonedDateTime
with the specified period in months subtracted.
This method subtracts the specified amount to the months field in four steps:
ZoneResolvers.retainOffset()
For example, 2007-03-31 minus one month would result in the invalid date 2007-04-31. Instead of returning an invalid result, the last valid day of the month, 2007-04-30, is selected instead.
This instance is immutable and unaffected by this method call.
months
- the months to subtract, positive or negativeZonedDateTime
based on this date-time with the months subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusWeeks(long weeks)
ZonedDateTime
with the specified period in weeks subtracted.
This method subtracts the specified amount in weeks to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 minus one week would result in the 2009-01-07.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
weeks
- the weeks to subtract, positive or negativeZonedDateTime
based on this date-time with the weeks subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusDays(long days)
ZonedDateTime
with the specified period in days subtracted.
This method subtracts the specified amount to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 minus one day would result in the 2009-01-01.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
days
- the days to subtract, positive or negativeZonedDateTime
based on this date-time with the days subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusHours(long hours)
ZonedDateTime
with the specified period in hours subtracted.
This method uses field based subtraction. This method changes the field by the specified number of hours. This may, at daylight savings cutover, result in a duration being subtracted that is more or less than the specified number of hours.
For example, consider a time-zone where the spring DST cutover means that the local times 01:00 to 01:59 do not exist. Using this method, subtracting a period of 2 hours from 02:30 will result in 00:30, but it is important to note that the change in duration was only 1 hour.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hours
- the hours to subtract, positive or negativeZonedDateTime
based on this date-time with the hours subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusMinutes(long minutes)
ZonedDateTime
with the specified period in minutes subtracted.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to subtract, positive or negativeZonedDateTime
based on this date-time with the minutes subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusSeconds(long seconds)
ZonedDateTime
with the specified period in seconds subtracted.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to subtract, positive or negativeZonedDateTime
based on this date-time with the seconds subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusNanos(long nanos)
ZonedDateTime
with the specified period in nanoseconds subtracted.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to subtract, positive or negativeZonedDateTime
based on this date-time with the nanoseconds subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusDuration(PeriodProvider periodProvider)
ZonedDateTime
with the specified duration subtracted.
This method converts
the period to a duration
based on the ISOChronology
seconds and nanoseconds units.
The duration is then subtracted from the instant
equivalent of this instance.
Subtracting a duration differs from subtracting a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then subtracting a duration of one hour from 02:30 will yield 00:30.
The subtraction of a duration is always absolute and zone-resolvers are not required.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to subtract, positive or negativeZonedDateTime
based on this date-time with the duration subtracted, never nullArithmeticException
- if the calculation exceeds the capacity of Instant
CalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusDuration(Duration duration)
ZonedDateTime
with the specified duration subtracted.
This subtracts the specified duration from this date-time, returning a new date-time.
The calculation is equivalent to subtraction on the instant
equivalent of this instance.
Subtracting a duration differs from subtracting a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then subtracting a duration of one hour from 02:30 will yield 00:30.
This instance is immutable and unaffected by this method call.
duration
- the duration to subtract, not nullZonedDateTime
based on this date-time with the duration subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic ZonedDateTime minusDuration(int hours, int minutes, int seconds, long nanos)
ZonedDateTime
with the specified duration subtracted.
Subtracting a duration differs from subtracting a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then subtracting a duration of one hour from 02:30 will yield 00:30.
The subtraction of a duration is always absolute and zone-resolvers are not required.
This instance is immutable and unaffected by this method call.
hours
- the hours to subtract, positive or negativeminutes
- the minutes to subtract, positive or negativeseconds
- the seconds to subtract, positive or negativenanos
- the nanos to subtract, positive or negativeZonedDateTime
based on this date-time with the duration subtracted, never nullArithmeticException
- if the calculation exceeds the capacity of Instant
CalendricalException
- if the result exceeds the supported rangepublic boolean matches(CalendricalMatcher matcher)
ZonedDateTime
matches the specified matcher.
Matchers can be used to query the date-time. A simple matcher might simply compare one of the fields, such as the year field. A more complex matcher might check if the date is the last day of the month.
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 Instant toInstant()
ZonedDateTime
to an Instant
.toInstant
in interface InstantProvider
public LocalDate toLocalDate()
ZonedDateTime
to a LocalDate
.toLocalDate
in interface DateProvider
public LocalTime toLocalTime()
ZonedDateTime
to a LocalTime
.toLocalTime
in interface TimeProvider
public LocalDateTime toLocalDateTime()
ZonedDateTime
to a LocalDateTime
.toLocalDateTime
in interface DateTimeProvider
public OffsetDate toOffsetDate()
ZonedDateTime
to a OffsetDate
.public OffsetTime toOffsetTime()
ZonedDateTime
to a OffsetTime
.public OffsetDateTime toOffsetDateTime()
ZonedDateTime
to a OffsetDateTime
.public long toEpochSeconds()
ZonedDateTime
to the number of seconds from the epoch
of 1970-01-01T00:00:00Z.
Instants on the time-line after the epoch are positive, earlier are negative.
public int compareTo(ZonedDateTime other)
ZonedDateTime
to another date-time based on the UTC
equivalent date-times then time-zone unique key.
The ordering is consistent with equals as it takes into account the date-time, offset and zone.
compareTo
in interface Comparable<ZonedDateTime>
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean isBefore(ZonedDateTime other)
This method differs from the comparison in compareTo(javax.time.calendar.ZonedDateTime)
in that it
only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().isBefore(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean isAfter(ZonedDateTime other)
This method differs from the comparison in compareTo(javax.time.calendar.ZonedDateTime)
in that it
only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().isAfter(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean equalInstant(ZonedDateTime other)
This method differs from the comparison in compareTo(javax.time.calendar.ZonedDateTime)
and equals(java.lang.Object)
in that it only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().equals(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean equals(Object other)
ZonedDateTime
is equal to the specified date-time.
This compares the date-time and the offset.
public int hashCode()
ZonedDateTime
.public String toString()
String
, such as
2007-12-03T10:15:30+01:00[Europe/Paris]
.
The output will be one of the following formats:
yyyy-MM-dd'T'HH:mmZZZZ'['I']'
yyyy-MM-dd'T'HH:mm:ssZZZZ'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnZZZZ'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnnnnZZZZ'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnnnnnnnZZZZ'['I']'
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<ZonedDateTime> rule()
ZonedDateTime
.Copyright © 2014. All rights reserved.