Class ZonedDateTime
- java.lang.Object
-
- javax.time.calendar.ZonedDateTime
-
- All Implemented Interfaces:
Serializable
,Comparable<ZonedDateTime>
,Calendrical
,CalendricalMatcher
,DateProvider
,DateTimeProvider
,TimeProvider
,InstantProvider
public final class ZonedDateTime extends Object implements InstantProvider, DateTimeProvider, Calendrical, CalendricalMatcher, Comparable<ZonedDateTime>, Serializable
A date-time with a time-zone in the ISO-8601 calendar system, such as2007-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 aZonedDateTime
.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 inZoneResolvers
provide strategies for handling these cases. The methodswithEarlierOffsetAtOverlap()
andwithLaterOffsetAtOverlap()
provide further control for overlaps.ZonedDateTime is immutable and thread-safe.
- Author:
- Michael Nascimento Santos, Stephen Colebourne
- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description int
compareTo(ZonedDateTime other)
Compares thisZonedDateTime
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 thisZonedDateTime
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 enumDayOfWeek
.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 enumMonthOfYear
.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 thisZonedDateTime
.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 thisZonedDateTime
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 thisZonedDateTime
with the specified period subtracted.ZonedDateTime
minus(PeriodProvider periodProvider, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
with the specified period subtracted.ZonedDateTime
minusDays(long days)
Returns a copy of thisZonedDateTime
with the specified period in days subtracted.ZonedDateTime
minusDuration(int hours, int minutes, int seconds, long nanos)
Returns a copy of thisZonedDateTime
with the specified duration subtracted.ZonedDateTime
minusDuration(PeriodProvider periodProvider)
Returns a copy of thisZonedDateTime
with the specified duration subtracted.ZonedDateTime
minusDuration(Duration duration)
Returns a copy of thisZonedDateTime
with the specified duration subtracted.ZonedDateTime
minusHours(long hours)
Returns a copy of thisZonedDateTime
with the specified period in hours subtracted.ZonedDateTime
minusMinutes(long minutes)
Returns a copy of thisZonedDateTime
with the specified period in minutes subtracted.ZonedDateTime
minusMonths(long months)
Returns a copy of thisZonedDateTime
with the specified period in months subtracted.ZonedDateTime
minusNanos(long nanos)
Returns a copy of thisZonedDateTime
with the specified period in nanoseconds subtracted.ZonedDateTime
minusSeconds(long seconds)
Returns a copy of thisZonedDateTime
with the specified period in seconds subtracted.ZonedDateTime
minusWeeks(long weeks)
Returns a copy of thisZonedDateTime
with the specified period in weeks subtracted.ZonedDateTime
minusYears(long years)
Returns a copy of thisZonedDateTime
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(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone)
Obtains an instance ofZonedDateTime
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 ofZonedDateTime
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 ofZonedDateTime
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 ofZonedDateTime
from year, month, day, hour, minute, second, nanosecond and time-zone providing a resolver to handle an invalid date-time.static ZonedDateTime
of(DateProvider dateProvider, TimeProvider timeProvider, TimeZone zone)
Obtains an instance ofZonedDateTime
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 ofZonedDateTime
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 ofZonedDateTime
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 ofZonedDateTime
from a local date-time providing a resolver to handle an invalid date-time.static ZonedDateTime
of(OffsetDateTime dateTime, TimeZone zone)
Obtains an instance ofZonedDateTime
from anOffsetDateTime
ensuring that the offset provided is valid for the time-zone.static ZonedDateTime
ofEpochSeconds(long epochSeconds, TimeZone zone)
Obtains an instance ofZonedDateTime
using seconds from the epoch of 1970-01-01T00:00:00Z.static ZonedDateTime
ofInstant(OffsetDateTime dateTime, TimeZone zone)
Obtains an instance ofZonedDateTime
from the instant of anOffsetDateTime
.static ZonedDateTime
ofInstant(InstantProvider instantProvider, TimeZone zone)
Obtains an instance ofZonedDateTime
from anInstant
.static ZonedDateTime
parse(String text)
Obtains an instance ofZonedDateTime
from a text string such as2007-12-03T10:15:30+01:00[Europe/Paris]
.static ZonedDateTime
parse(String text, DateTimeFormatter formatter)
Obtains an instance ofZonedDateTime
from a text string using a specific formatter.ZonedDateTime
plus(PeriodProvider periodProvider)
Returns a copy of thisZonedDateTime
with the specified period added.ZonedDateTime
plus(PeriodProvider periodProvider, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
with the specified period added.ZonedDateTime
plusDays(long days)
Returns a copy of thisZonedDateTime
with the specified period in days added.ZonedDateTime
plusDuration(int hours, int minutes, int seconds, long nanos)
Returns a copy of thisZonedDateTime
with the specified duration added.ZonedDateTime
plusDuration(PeriodProvider periodProvider)
Returns a copy of thisZonedDateTime
with the specified duration added.ZonedDateTime
plusDuration(Duration duration)
Returns a copy of thisZonedDateTime
with the specified duration added.ZonedDateTime
plusHours(long hours)
Returns a copy of thisZonedDateTime
with the specified period in hours added.ZonedDateTime
plusMinutes(long minutes)
Returns a copy of thisZonedDateTime
with the specified period in minutes added.ZonedDateTime
plusMonths(long months)
Returns a copy of thisZonedDateTime
with the specified period in months added.ZonedDateTime
plusNanos(long nanos)
Returns a copy of thisZonedDateTime
with the specified period in nanoseconds added.ZonedDateTime
plusSeconds(long seconds)
Returns a copy of thisZonedDateTime
with the specified period in seconds added.ZonedDateTime
plusWeeks(long weeks)
Returns a copy of thisZonedDateTime
with the specified period in weeks added.ZonedDateTime
plusYears(long years)
Returns a copy of thisZonedDateTime
with the specified period in years added.static CalendricalRule<ZonedDateTime>
rule()
Gets the rule forZonedDateTime
.long
toEpochSeconds()
Converts thisZonedDateTime
to the number of seconds from the epoch of 1970-01-01T00:00:00Z.Instant
toInstant()
Converts thisZonedDateTime
to anInstant
.LocalDate
toLocalDate()
Converts thisZonedDateTime
to aLocalDate
.LocalDateTime
toLocalDateTime()
Converts thisZonedDateTime
to aLocalDateTime
.LocalTime
toLocalTime()
Converts thisZonedDateTime
to aLocalTime
.OffsetDate
toOffsetDate()
Converts thisZonedDateTime
to aOffsetDate
.OffsetDateTime
toOffsetDateTime()
Converts thisZonedDateTime
to aOffsetDateTime
.OffsetTime
toOffsetTime()
Converts thisZonedDateTime
to aOffsetTime
.String
toString()
Outputs this date-time as aString
, such as2007-12-03T10:15:30+01:00[Europe/Paris]
.String
toString(DateTimeFormatter formatter)
Outputs this date-time as aString
using the formatter.ZonedDateTime
with(DateAdjuster adjuster)
Returns a copy of thisZonedDateTime
with the date altered using the adjuster.ZonedDateTime
with(DateAdjuster adjuster, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
with the date altered using the adjuster, providing a resolver to handle an invalid date-time.ZonedDateTime
with(TimeAdjuster adjuster)
Returns a copy of thisZonedDateTime
with the time altered using the adjuster.ZonedDateTime
with(TimeAdjuster adjuster, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
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 thisZonedDateTime
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 thisZonedDateTime
with the day-of-month value altered.ZonedDateTime
withDayOfYear(int dayOfYear)
Returns a copy of thisZonedDateTime
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 thisZonedDateTime
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 thisZonedDateTime
with the minute-of-hour value altered.ZonedDateTime
withMonthOfYear(int monthOfYear)
Returns a copy of thisZonedDateTime
with the month-of-year value altered.ZonedDateTime
withNanoOfSecond(int nanoOfSecond)
Returns a copy of thisZonedDateTime
with the nano-of-second value altered.ZonedDateTime
withSecondOfMinute(int secondOfMinute)
Returns a copy of thisZonedDateTime
with the second-of-minute value altered.ZonedDateTime
withTime(int hourOfDay, int minuteOfHour)
Returns a copy of thisZonedDateTime
with the time values altered.ZonedDateTime
withTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
Returns a copy of thisZonedDateTime
with the time values altered.ZonedDateTime
withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
Returns a copy of thisZonedDateTime
with the time values altered.ZonedDateTime
withYear(int year)
Returns a copy of thisZonedDateTime
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.
-
-
-
Method Detail
-
now
public static ZonedDateTime now()
Obtains the current date-time from the system clock in the default time-zone.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.
- Returns:
- the current date-time using the system clock, never null
-
now
public static ZonedDateTime now(Clock clock)
Obtains the current date-time from the specified 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
.- Parameters:
clock
- the clock to use, not null- Returns:
- the current date-time, never null
-
of
public static ZonedDateTime of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone)
Obtains an instance ofZonedDateTime
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.
- Parameters:
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 null- Returns:
- the zoned date-time, never null
- Throws:
IllegalCalendarFieldValueException
- 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-zone
-
of
public static ZonedDateTime of(int year, MonthOfYear monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone, ZoneResolver resolver)
Obtains an instance ofZonedDateTime
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.- Parameters:
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 null- Returns:
- the zoned date-time, never null
- Throws:
IllegalCalendarFieldValueException
- 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-time
-
of
public static ZonedDateTime of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone)
Obtains an instance ofZonedDateTime
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.
- Parameters:
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 null- Returns:
- the zoned date-time, never null
- Throws:
IllegalCalendarFieldValueException
- 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-zone
-
of
public static ZonedDateTime of(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, TimeZone zone, ZoneResolver resolver)
Obtains an instance ofZonedDateTime
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.- Parameters:
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 null- Returns:
- the zoned date-time, never null
- Throws:
IllegalCalendarFieldValueException
- 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-time
-
of
public static ZonedDateTime of(DateProvider dateProvider, TimeProvider timeProvider, TimeZone zone)
Obtains an instance ofZonedDateTime
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.- Parameters:
dateProvider
- the date provider to use, not nulltimeProvider
- the time provider to use, not nullzone
- the time-zone, not null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- if the local date-time is invalid for the time-zone
-
of
public static ZonedDateTime of(DateProvider dateProvider, TimeProvider timeProvider, TimeZone zone, ZoneResolver resolver)
Obtains an instance ofZonedDateTime
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. SeeZoneResolvers
for common resolver implementations.- Parameters:
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 null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- if the resolver cannot resolve an invalid local date-time
-
of
public static ZonedDateTime of(DateTimeProvider dateTimeProvider, TimeZone zone)
Obtains an instance ofZonedDateTime
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.- Parameters:
dateTimeProvider
- the date-time provider to use, not nullzone
- the time-zone, not null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- if the local date-time is invalid for the time-zone
-
of
public static ZonedDateTime of(DateTimeProvider dateTimeProvider, TimeZone zone, ZoneResolver resolver)
Obtains an instance ofZonedDateTime
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. SeeZoneResolvers
for common resolver implementations.- Parameters:
dateTimeProvider
- the date-time provider to use, not nullzone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- if the resolver cannot resolve an invalid local date-time
-
of
public static ZonedDateTime of(OffsetDateTime dateTime, TimeZone zone)
Obtains an instance ofZonedDateTime
from anOffsetDateTime
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. ThefromInstant
method will change the date and time if necessary to retain the same instant.- Parameters:
dateTime
- the offset date-time to use, not nullzone
- the time-zone, not null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- 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-time
-
ofInstant
public static ZonedDateTime ofInstant(InstantProvider instantProvider, TimeZone zone)
Obtains an instance ofZonedDateTime
from anInstant
.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.
- Parameters:
instantProvider
- the instant to convert, not nullzone
- the time-zone, not null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- if the result exceeds the supported range
-
ofInstant
public static ZonedDateTime ofInstant(OffsetDateTime dateTime, TimeZone zone)
Obtains an instance ofZonedDateTime
from the instant of anOffsetDateTime
.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)
. ThefromInstant
method will change the date and time if necessary to retain the same instant. ThedateTime
method will retain the date and time and throw an exception if the offset is invalid.- Parameters:
dateTime
- the offset date-time to use, not nullzone
- the time-zone, not null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- if the result exceeds the supported range
-
ofEpochSeconds
public static ZonedDateTime ofEpochSeconds(long epochSeconds, TimeZone zone)
Obtains an instance ofZonedDateTime
using seconds from the epoch of 1970-01-01T00:00:00Z.The nanosecond field is set to zero.
- Parameters:
epochSeconds
- the number of seconds from the epoch of 1970-01-01T00:00:00Zzone
- the time-zone, not null- Returns:
- the zoned date-time, never null
- Throws:
CalendricalException
- if the result exceeds the supported range
-
parse
public static ZonedDateTime parse(String text)
Obtains an instance ofZonedDateTime
from a text string such as2007-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()
.- Parameters:
text
- the text to parse such as '2007-12-03T10:15:30+01:00[Europe/Paris]', not null- Returns:
- the parsed zoned date-time, never null
- Throws:
CalendricalException
- if the text cannot be parsed
-
parse
public static ZonedDateTime parse(String text, DateTimeFormatter formatter)
Obtains an instance ofZonedDateTime
from a text string using a specific formatter.The text is parsed using the formatter, returning a date-time.
- Parameters:
text
- the text to parse, not nullformatter
- the formatter to use, not null- Returns:
- the parsed zoned date-time, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot parseCalendricalException
- if the text cannot be parsed
-
getChronology
public ISOChronology getChronology()
Gets the chronology that this date-time uses, which is the ISO calendar system.- Returns:
- the ISO chronology, never null
-
get
public <T> T get(CalendricalRule<T> rule)
Gets the value of the specified calendrical 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.- Specified by:
get
in interfaceCalendrical
- Parameters:
rule
- the rule to use, not null- Returns:
- the value for the rule, null if the value cannot be returned
-
withDateTime
public ZonedDateTime withDateTime(DateTimeProvider dateTimeProvider)
Returns a copy of this ZonedDateTime with a different local date-time.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.
- Parameters:
dateTimeProvider
- the local date-time to change to, not null- Returns:
- a
ZonedDateTime
based on this date-time with the requested date-time, never null
-
getOffset
public ZoneOffset getOffset()
Gets the zone offset, such as '+01:00'.- Returns:
- the zone offset, never null
-
withEarlierOffsetAtOverlap
public 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.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.
- Returns:
- a
ZonedDateTime
based on this date-time with the earlier offset, never null - Throws:
CalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-time
-
withLaterOffsetAtOverlap
public 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.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.
- Returns:
- a
ZonedDateTime
based on this date-time with the later offset, never null - Throws:
CalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-time
-
getZone
public TimeZone getZone()
Gets the time-zone, such as 'Europe/Paris'.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. ThegetApplicableRules()
method will resolve the actual zone-rules.- Returns:
- the time-zone, never null
-
withZoneSameLocal
public ZonedDateTime withZoneSameLocal(TimeZone zone)
Returns a copy of this ZonedDateTime with a different time-zone, retaining the local date-time if possible.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.
- Parameters:
zone
- the time-zone to change to, not null- Returns:
- a
ZonedDateTime
based on this date-time with the requested zone, never null
-
withZoneSameLocal
public ZonedDateTime withZoneSameLocal(TimeZone zone, ZoneResolver resolver)
Returns a copy of this ZonedDateTime with a different time-zone, retaining the local date-time if possible.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.
- Parameters:
zone
- the time-zone to change to, not nullresolver
- the resolver to use, not null- Returns:
- a
ZonedDateTime
based on this date-time with the requested zone, never null
-
withZoneSameInstant
public ZonedDateTime withZoneSameInstant(TimeZone zone)
Returns a copy of this ZonedDateTime with a different time-zone, retaining the instant.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)
.- Parameters:
zone
- the time-zone to change to, not null- Returns:
- a
ZonedDateTime
based on this date-time with the requested zone, never null - Throws:
CalendarConversionException
- if the result exceeds the supported date range
-
getApplicableZone
public TimeZone getApplicableZone()
Calculates the applicable versioned time-zone, such as 'Europe/Paris#2009b'.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.
- Returns:
- the time-zone complete with version, never null
- Throws:
CalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-time
-
getApplicableRules
public ZoneRules getApplicableRules()
Calculates the zone rules applicable for this date-time.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.
- Returns:
- the time-zone rules, never null
- Throws:
CalendricalException
- if no rules can be found for the zoneCalendricalException
- if no rules are valid for this date-time
-
getYear
public int getYear()
Gets the year field.This method returns the primitive
int
value for the year. Additional information about the year can be obtained by creating aYear
.- Returns:
- the year, from MIN_YEAR to MAX_YEAR
-
getMonthOfYear
public MonthOfYear getMonthOfYear()
Gets the month-of-year field, which is an enumMonthOfYear
.This method returns the enum
MonthOfYear
for the month. This avoids confusion as to whatint
values mean. If you need access to the primitiveint
value then the enum provides theint 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.- Returns:
- the month-of-year, never null
-
getDayOfMonth
public int getDayOfMonth()
Gets the day-of-month field.This method returns the primitive
int
value for the day-of-month.- Returns:
- the day-of-month, from 1 to 31
-
getDayOfYear
public int getDayOfYear()
Gets the day-of-year field.This method returns the primitive
int
value for the day-of-year.- Returns:
- the day-of-year, from 1 to 365, or 366 in a leap year
-
getDayOfWeek
public DayOfWeek getDayOfWeek()
Gets the day-of-week field, which is an enumDayOfWeek
.This method returns the enum
DayOfWeek
for the day-of-week. This avoids confusion as to whatint
values mean. If you need access to the primitiveint
value then the enum provides theint value
.Additional information can be obtained from the
DayOfWeek
. This includes textual names of the values.- Returns:
- the day-of-week, never null
-
getHourOfDay
public int getHourOfDay()
Gets the hour-of-day field.- Returns:
- the hour-of-day, from 0 to 23
-
getMinuteOfHour
public int getMinuteOfHour()
Gets the minute-of-hour field.- Returns:
- the minute-of-hour, from 0 to 59
-
getSecondOfMinute
public int getSecondOfMinute()
Gets the second-of-minute field.- Returns:
- the second-of-minute, from 0 to 59
-
getNanoOfSecond
public int getNanoOfSecond()
Gets the nano-of-second field.- Returns:
- the nano-of-second, from 0 to 999,999,999
-
isLeapYear
public boolean isLeapYear()
Checks if the year is a leap year, according to the ISO proleptic calendar system rules.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.
- Returns:
- true if the year is leap, false otherwise
-
with
public ZonedDateTime with(DateAdjuster adjuster)
Returns a copy of thisZonedDateTime
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.
- Parameters:
adjuster
- the adjuster to use, not null- Returns:
- a
ZonedDateTime
based on this date-time with the date adjusted, never null - Throws:
IllegalArgumentException
- if the adjuster returned null
-
with
public ZonedDateTime with(DateAdjuster adjuster, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
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.
- Parameters:
adjuster
- the adjuster to use, not nullresolver
- the resolver to use, not null- Returns:
- a
ZonedDateTime
based on this date-time with the date adjusted, never null - Throws:
IllegalArgumentException
- if the adjuster returned nullIllegalCalendarFieldValueException
- if the resolver cannot resolve the date-time
-
with
public ZonedDateTime with(TimeAdjuster adjuster)
Returns a copy of thisZonedDateTime
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.
- Parameters:
adjuster
- the adjuster to use, not null- Returns:
- a
ZonedDateTime
based on this date-time with the time adjusted, never null - Throws:
IllegalArgumentException
- if the adjuster returned null
-
with
public ZonedDateTime with(TimeAdjuster adjuster, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
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.
- Parameters:
adjuster
- the adjuster to use, not nullresolver
- the resolver to use, not null- Returns:
- a
ZonedDateTime
based on this date-time with the time adjusted, never null - Throws:
IllegalArgumentException
- if the adjuster returned nullIllegalCalendarFieldValueException
- if the resolver cannot resolve the date-time
-
withYear
public ZonedDateTime withYear(int year)
Returns a copy of thisZonedDateTime
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.
- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEAR- Returns:
- a
ZonedDateTime
based on this date-time with the requested year, never null - Throws:
IllegalCalendarFieldValueException
- if the year value is invalid
-
withMonthOfYear
public ZonedDateTime withMonthOfYear(int monthOfYear)
Returns a copy of thisZonedDateTime
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.
- Parameters:
monthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)- Returns:
- a
ZonedDateTime
based on this date-time with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month value is invalid
-
withDayOfMonth
public ZonedDateTime withDayOfMonth(int dayOfMonth)
Returns a copy of thisZonedDateTime
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.
- Parameters:
dayOfMonth
- the day-of-month to represent, from 1 to 31- Returns:
- a
ZonedDateTime
based on this date-time with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-month value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
withDayOfYear
public ZonedDateTime withDayOfYear(int dayOfYear)
Returns a copy of thisZonedDateTime
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.
- Parameters:
dayOfYear
- the day-of-year to set in the returned date, from 1 to 365-366- Returns:
- a
ZonedDateTime
based on this date with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-year value is invalidInvalidCalendarFieldException
- if the day-of-year is invalid for the year
-
withDate
public ZonedDateTime withDate(int year, int monthOfYear, int dayOfMonth)
Returns a copy of thisZonedDateTime
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.
- Parameters:
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 31- Returns:
- a
ZonedDateTime
based on this date-time with the requested date, never null - Throws:
IllegalCalendarFieldValueException
- if the any field value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month-year
-
withHourOfDay
public ZonedDateTime withHourOfDay(int hourOfDay)
Returns a copy of thisZonedDateTime
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.
- Parameters:
hourOfDay
- the hour-of-day to represent, from 0 to 23- Returns:
- a
ZonedDateTime
based on this date-time with the requested hour, never null - Throws:
IllegalCalendarFieldValueException
- if the hour value is invalid
-
withMinuteOfHour
public ZonedDateTime withMinuteOfHour(int minuteOfHour)
Returns a copy of thisZonedDateTime
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.
- Parameters:
minuteOfHour
- the minute-of-hour to represent, from 0 to 59- Returns:
- a
ZonedDateTime
based on this date-time with the requested minute, never null - Throws:
IllegalCalendarFieldValueException
- if the minute value is invalid
-
withSecondOfMinute
public ZonedDateTime withSecondOfMinute(int secondOfMinute)
Returns a copy of thisZonedDateTime
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.
- Parameters:
secondOfMinute
- the second-of-minute to represent, from 0 to 59- Returns:
- a
ZonedDateTime
based on this date-time with the requested second, never null - Throws:
IllegalCalendarFieldValueException
- if the second value is invalid
-
withNanoOfSecond
public ZonedDateTime withNanoOfSecond(int nanoOfSecond)
Returns a copy of thisZonedDateTime
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.
- Parameters:
nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999- Returns:
- a
ZonedDateTime
based on this date-time with the requested nanosecond, never null - Throws:
IllegalCalendarFieldValueException
- if the nanos value is invalid
-
withTime
public ZonedDateTime withTime(int hourOfDay, int minuteOfHour)
Returns a copy of thisZonedDateTime
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.
- Parameters:
hourOfDay
- the hour-of-day to represent, from 0 to 23minuteOfHour
- the minute-of-hour to represent, from 0 to 59- Returns:
- a
ZonedDateTime
based on this date-time with the requested time, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalid
-
withTime
public ZonedDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute)
Returns a copy of thisZonedDateTime
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.
- Parameters:
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 59- Returns:
- a
ZonedDateTime
based on this date-time with the requested time, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalid
-
withTime
public ZonedDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond)
Returns a copy of thisZonedDateTime
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.
- Parameters:
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,999- Returns:
- a
ZonedDateTime
based on this date-time with the requested time, never null - Throws:
IllegalCalendarFieldValueException
- if any field value is invalid
-
plus
public ZonedDateTime plus(PeriodProvider periodProvider)
Returns a copy of thisZonedDateTime
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 thePeriod.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.
- Parameters:
periodProvider
- the period to add, not null- Returns:
- a
ZonedDateTime
based on this date-time with the period added, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
CalendricalException
- if the result exceeds the supported range
-
plus
public ZonedDateTime plus(PeriodProvider periodProvider, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
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 thePeriod.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.
- Parameters:
periodProvider
- the period to add, not null- Returns:
- a
ZonedDateTime
based on this date-time with the period added, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
CalendricalException
- if the result exceeds the supported range
-
plusYears
public ZonedDateTime plusYears(long years)
Returns a copy of thisZonedDateTime
with the specified period in years added.This method add the specified amount to the years field in four steps:
- Add the input years to the year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
- Resolve the date-time using
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.
- Parameters:
years
- the years to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the years added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusMonths
public ZonedDateTime plusMonths(long months)
Returns a copy of thisZonedDateTime
with the specified period in months added.This method adds the specified amount to the months field in four steps:
- Add the input months to the month-of-year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
- Resolve the date-time using
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.
- Parameters:
months
- the months to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the months added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusWeeks
public ZonedDateTime plusWeeks(long weeks)
Returns a copy of thisZonedDateTime
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.
- Parameters:
weeks
- the weeks to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the weeks added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusDays
public ZonedDateTime plusDays(long days)
Returns a copy of thisZonedDateTime
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.
- Parameters:
days
- the days to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the days added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusHours
public ZonedDateTime plusHours(long hours)
Returns a copy of thisZonedDateTime
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.
- Parameters:
hours
- the hours to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the hours added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusMinutes
public ZonedDateTime plusMinutes(long minutes)
Returns a copy of thisZonedDateTime
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.
- Parameters:
minutes
- the minutes to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the minutes added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusSeconds
public ZonedDateTime plusSeconds(long seconds)
Returns a copy of thisZonedDateTime
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.
- Parameters:
seconds
- the seconds to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the seconds added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusNanos
public ZonedDateTime plusNanos(long nanos)
Returns a copy of thisZonedDateTime
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.
- Parameters:
nanos
- the nanos to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the nanoseconds added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusDuration
public ZonedDateTime plusDuration(PeriodProvider periodProvider)
Returns a copy of thisZonedDateTime
with the specified duration added.This method
converts
the period to a duration based on theISOChronology
seconds and nanoseconds units. The duration is then added to theinstant
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.
- Parameters:
periodProvider
- the period to add, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the duration added, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofInstant
CalendricalException
- if the result exceeds the supported range
-
plusDuration
public ZonedDateTime plusDuration(Duration duration)
Returns a copy of thisZonedDateTime
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.
- Parameters:
duration
- the duration to add, not null- Returns:
- a
ZonedDateTime
based on this date-time with the duration added, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
plusDuration
public ZonedDateTime plusDuration(int hours, int minutes, int seconds, long nanos)
Returns a copy of thisZonedDateTime
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.
- Parameters:
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 negative- Returns:
- a
ZonedDateTime
based on this date-time with the duration added, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofInstant
CalendricalException
- if the result exceeds the supported range
-
minus
public ZonedDateTime minus(PeriodProvider periodProvider)
Returns a copy of thisZonedDateTime
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 thePeriod.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.
- Parameters:
periodProvider
- the period to subtract, not null- Returns:
- a
ZonedDateTime
based on this date-time with the period subtracted, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
CalendricalException
- if the result exceeds the supported range
-
minus
public ZonedDateTime minus(PeriodProvider periodProvider, ZoneResolver resolver)
Returns a copy of thisZonedDateTime
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 thePeriod.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.
- Parameters:
periodProvider
- the period to subtract, not null- Returns:
- a
ZonedDateTime
based on this date-time with the period subtracted, never null - Throws:
CalendricalException
- if the specified period cannot be converted to aPeriod
CalendricalException
- if the result exceeds the supported range
-
minusYears
public ZonedDateTime minusYears(long years)
Returns a copy of thisZonedDateTime
with the specified period in years subtracted.This method subtracts the specified amount to the years field in four steps:
- Add the input years to the year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
- Resolve the date-time using
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.
- Parameters:
years
- the years to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the years subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusMonths
public ZonedDateTime minusMonths(long months)
Returns a copy of thisZonedDateTime
with the specified period in months subtracted.This method subtracts the specified amount to the months field in four steps:
- Add the input months to the month-of-year field
- Check if the resulting date would be invalid
- Adjust the day-of-month to the last valid day if necessary
- Resolve the date-time using
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.
- Parameters:
months
- the months to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the months subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusWeeks
public ZonedDateTime minusWeeks(long weeks)
Returns a copy of thisZonedDateTime
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.
- Parameters:
weeks
- the weeks to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the weeks subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusDays
public ZonedDateTime minusDays(long days)
Returns a copy of thisZonedDateTime
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.
- Parameters:
days
- the days to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the days subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusHours
public ZonedDateTime minusHours(long hours)
Returns a copy of thisZonedDateTime
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.
- Parameters:
hours
- the hours to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the hours subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusMinutes
public ZonedDateTime minusMinutes(long minutes)
Returns a copy of thisZonedDateTime
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.
- Parameters:
minutes
- the minutes to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the minutes subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusSeconds
public ZonedDateTime minusSeconds(long seconds)
Returns a copy of thisZonedDateTime
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.
- Parameters:
seconds
- the seconds to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the seconds subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusNanos
public ZonedDateTime minusNanos(long nanos)
Returns a copy of thisZonedDateTime
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.
- Parameters:
nanos
- the nanos to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the nanoseconds subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusDuration
public ZonedDateTime minusDuration(PeriodProvider periodProvider)
Returns a copy of thisZonedDateTime
with the specified duration subtracted.This method
converts
the period to a duration based on theISOChronology
seconds and nanoseconds units. The duration is then subtracted from theinstant
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.
- Parameters:
periodProvider
- the period to subtract, positive or negative- Returns:
- a
ZonedDateTime
based on this date-time with the duration subtracted, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofInstant
CalendricalException
- if the result exceeds the supported range
-
minusDuration
public ZonedDateTime minusDuration(Duration duration)
Returns a copy of thisZonedDateTime
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.
- Parameters:
duration
- the duration to subtract, not null- Returns:
- a
ZonedDateTime
based on this date-time with the duration subtracted, never null - Throws:
CalendricalException
- if the result exceeds the supported range
-
minusDuration
public ZonedDateTime minusDuration(int hours, int minutes, int seconds, long nanos)
Returns a copy of thisZonedDateTime
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.
- Parameters:
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 negative- Returns:
- a
ZonedDateTime
based on this date-time with the duration subtracted, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofInstant
CalendricalException
- if the result exceeds the supported range
-
matches
public boolean matches(CalendricalMatcher matcher)
Checks whether thisZonedDateTime
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.
- Parameters:
matcher
- the matcher to use, not null- Returns:
- true if this date-time matches the matcher, false otherwise
-
matchesCalendrical
public boolean matchesCalendrical(Calendrical calendrical)
Checks if the date-time extracted from the calendrical matches this.This method implements the
CalendricalMatcher
interface. It is intended that applications usematches(javax.time.calendar.CalendricalMatcher)
rather than this method.- Specified by:
matchesCalendrical
in interfaceCalendricalMatcher
- Parameters:
calendrical
- the calendrical to match, not null- Returns:
- true if the calendrical matches, false otherwise
-
toInstant
public Instant toInstant()
Converts thisZonedDateTime
to anInstant
.- Specified by:
toInstant
in interfaceInstantProvider
- Returns:
- an Instant representing the same instant, never null
-
toLocalDate
public LocalDate toLocalDate()
Converts thisZonedDateTime
to aLocalDate
.- Specified by:
toLocalDate
in interfaceDateProvider
- Returns:
- a LocalDate representing the date fields of this date-time, never null
-
toLocalTime
public LocalTime toLocalTime()
Converts thisZonedDateTime
to aLocalTime
.- Specified by:
toLocalTime
in interfaceTimeProvider
- Returns:
- a LocalTime representing the time fields of this date-time, never null
-
toLocalDateTime
public LocalDateTime toLocalDateTime()
Converts thisZonedDateTime
to aLocalDateTime
.- Specified by:
toLocalDateTime
in interfaceDateTimeProvider
- Returns:
- a LocalDateTime representing the fields of this date-time, never null
-
toOffsetDate
public OffsetDate toOffsetDate()
Converts thisZonedDateTime
to aOffsetDate
.- Returns:
- a OffsetDate representing the date fields of this date-time, never null
-
toOffsetTime
public OffsetTime toOffsetTime()
Converts thisZonedDateTime
to aOffsetTime
.- Returns:
- a OffsetTime representing the time fields of this date-time, never null
-
toOffsetDateTime
public OffsetDateTime toOffsetDateTime()
Converts thisZonedDateTime
to aOffsetDateTime
.- Returns:
- a OffsetDateTime representing the fields of this date-time, never null
-
toEpochSeconds
public long toEpochSeconds()
Converts thisZonedDateTime
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.
- Returns:
- the number of seconds from the epoch of 1970-01-01T00:00:00Z
-
compareTo
public int compareTo(ZonedDateTime other)
Compares thisZonedDateTime
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.
- Specified by:
compareTo
in interfaceComparable<ZonedDateTime>
- Parameters:
other
- the other date-time to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
- Throws:
NullPointerException
- ifother
is null
-
isBefore
public boolean isBefore(ZonedDateTime other)
Checks if the instant of this date-time is before that of the specified date-time.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 usingdateTime1.toInstant().isBefore(dateTime2.toInstant());
.- Parameters:
other
- the other date-time to compare to, not null- Returns:
- true if this point is before the specified date-time
- Throws:
NullPointerException
- ifother
is null
-
isAfter
public boolean isAfter(ZonedDateTime other)
Checks if the instant of this date-time is after that of the specified date-time.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 usingdateTime1.toInstant().isAfter(dateTime2.toInstant());
.- Parameters:
other
- the other date-time to compare to, not null- Returns:
- true if this is after the specified date-time
- Throws:
NullPointerException
- ifother
is null
-
equalInstant
public boolean equalInstant(ZonedDateTime other)
Checks if the instant of this date-time is equal to that of the specified date-time.This method differs from the comparison in
compareTo(javax.time.calendar.ZonedDateTime)
andequals(java.lang.Object)
in that it only compares the instant of the date-time. This is equivalent to usingdateTime1.toInstant().equals(dateTime2.toInstant());
.- Parameters:
other
- the other date-time to compare to, not null- Returns:
- true if this is after the specified date-time
- Throws:
NullPointerException
- ifother
is null
-
equals
public boolean equals(Object other)
Checks if thisZonedDateTime
is equal to the specified date-time.This compares the date-time and the offset.
-
hashCode
public int hashCode()
A hash code for thisZonedDateTime
.
-
toString
public String toString()
Outputs this date-time as aString
, such as2007-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']'
-
toString
public String toString(DateTimeFormatter formatter)
Outputs this date-time as aString
using the formatter.- Parameters:
formatter
- the formatter to use, not null- Returns:
- the formatted date-time string, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot printCalendricalPrintException
- if an error occurs during printing
-
rule
public static CalendricalRule<ZonedDateTime> rule()
Gets the rule forZonedDateTime
.- Returns:
- the rule for the date-time, never null
-
-