ZonedDateTime (ThreeTen date and time API)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.time.calendar
Class ZonedDateTime

java.lang.Object
  javax.time.calendar.ZonedDateTime

All Implemented Interfaces:: java.io.Serializable, java.lang.Comparable<ZonedDateTime>, Calendrical, CalendricalMatcher, InstantProvider

public final class ZonedDateTime
extends java.lang.Object
implements InstantProvider, Calendrical, CalendricalMatcher, java.lang.Comparable<ZonedDateTime>, java.io.Serializable
extends java.lang.Object
implements InstantProvider, Calendrical, CalendricalMatcher, java.lang.Comparable<ZonedDateTime>, java.io.Serializable

A date-time with a time-zone in the ISO-8601 calendar system, such as 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. 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.

Author:: Michael Nascimento Santos, Stephen Colebourne
See Also:: Serialized Form

Method Summary

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(java.lang.Object obj)
Checks if this date-time is equal to another date-time.

static ZonedDateTime from(Calendrical... calendricals)
Obtains an instance of ZonedDateTime from a set of calendricals.





<T> T

get(CalendricalRule<T> ruleToDerive)
Gets the value of the specified calendrical rule.

ZoneRules getApplicableRules()
Calculates the zone rules applicable for this date-time.

ZoneId getApplicableZone()
Calculates the applicable versioned time-zone, such as 'Europe/Paris#2009b'.

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.

ZoneId getZone()
Gets the time-zone, such as 'Europe/Paris'.

int hashCode()
A hash code for this date-time.

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(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute, int nanoOfSecond, ZoneId 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, ZoneId 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, ZoneId 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, ZoneId 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(LocalDate date, LocalTime time, ZoneId 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(LocalDate date, LocalTime time, ZoneId 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(LocalDateTime dateTime, ZoneId 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(LocalDateTime dateTime, ZoneId 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(OffsetDateTime dateTime, ZoneId zone)
Obtains an instance of ZonedDateTime from an OffsetDateTime ensuring that the offset provided is valid for the time-zone.

static ZonedDateTime ofEpochSecond(long epochSecond, ZoneId zone)
Obtains an instance of ZonedDateTime using seconds from the epoch of 1970-01-01T00:00:00Z.

static ZonedDateTime ofInstant(InstantProvider instantProvider, ZoneId zone)
Obtains an instance of ZonedDateTime from an InstantProvider.

static ZonedDateTime ofInstantUTC(InstantProvider instantProvider)
Obtains an instance of ZonedDateTime from an InstantProvider using the UTC zone.

static ZonedDateTime parse(java.lang.CharSequence text)
Obtains an instance of ZonedDateTime from a text string such as 2007-12-03T10:15:30+01:00[Europe/Paris].

static ZonedDateTime parse(java.lang.CharSequence 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 toEpochSecond()
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.

java.lang.String toString()
Outputs this date-time as a String, such as 2007-12-03T10:15:30+01:00[Europe/Paris].

java.lang.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 for invalid date-times.

ZonedDateTime with(MonthOfYear monthOfYear)
Returns a copy of this ZonedDateTime with the month-of-year value altered.

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 for invalid date-times.

ZonedDateTime withDate(int year, int monthOfYear, int dayOfMonth)
Returns a copy of this ZonedDateTime with the date values altered.

ZonedDateTime withDateTime(LocalDateTime dateTime)
Returns a copy of this ZonedDateTime with the local date-time altered.

ZonedDateTime withDateTime(LocalDateTime dateTime, ZoneResolver resolver)
Returns a copy of this ZonedDateTime with the local date-time altered, providing a resolver for invalid date-times.

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(ZoneId zone)
Returns a copy of this ZonedDateTime with a different time-zone, retaining the instant.

ZonedDateTime withZoneSameLocal(ZoneId zone)
Returns a copy of this ZonedDateTime with a different time-zone, retaining the local date-time if possible.

ZonedDateTime withZoneSameLocal(ZoneId zone, ZoneResolver resolver)
Returns a copy of this ZonedDateTime with a different time-zone, retaining the local date-time if possible.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Method Detail

rule

public static CalendricalRule<ZonedDateTime> rule()

Gets the rule for ZonedDateTime.

Returns:: the rule for the date-time, not null

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, not 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, not null

of

public static ZonedDateTime of(int year,
                               MonthOfYear monthOfYear,
                               int dayOfMonth,
                               int hourOfDay,
                               int minuteOfHour,
                               int secondOfMinute,
                               int nanoOfSecond,
                               ZoneId 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.

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_YEAR; monthOfYear - the month-of-year to represent, not null; dayOfMonth - the day-of-month to represent, from 1 to 31; hourOfDay - the hour-of-day to represent, from 0 to 23; minuteOfHour - the minute-of-hour to represent, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59; nanoOfSecond - the nano-of-second to represent, from 0 to 999,999,999; zone - the time-zone, not null
Returns:: the zoned date-time, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year; CalendricalException - 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,
                               ZoneId 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.

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_YEAR; monthOfYear - the month-of-year to represent, not null; dayOfMonth - the day-of-month to represent, from 1 to 31; hourOfDay - the hour-of-day to represent, from 0 to 23; minuteOfHour - the minute-of-hour to represent, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59; nanoOfSecond - the nano-of-second to represent, from 0 to 999,999,999; zone - the time-zone, not null; resolver - the resolver from local date-time to zoned, not null
Returns:: the zoned date-time, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year; CalendricalException - 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,
                               ZoneId 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.

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_YEAR; monthOfYear - the month-of-year to represent, from 1 (January) to 12 (December); dayOfMonth - the day-of-month to represent, from 1 to 31; hourOfDay - the hour-of-day to represent, from 0 to 23; minuteOfHour - the minute-of-hour to represent, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59; nanoOfSecond - the nano-of-second to represent, from 0 to 999,999,999; zone - the time-zone, not null
Returns:: the zoned date-time, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year; CalendricalException - 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,
                               ZoneId 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.

The day must be valid for the year and month or an exception will be thrown.

Parameters:: year - the year to represent, from MIN_YEAR to MAX_YEAR; monthOfYear - the month-of-year to represent, from 1 (January) to 12 (December); dayOfMonth - the day-of-month to represent, from 1 to 31; hourOfDay - the hour-of-day to represent, from 0 to 23; minuteOfHour - the minute-of-hour to represent, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59; nanoOfSecond - the nano-of-second to represent, from 0 to 999,999,999; zone - the time-zone, not null; resolver - the resolver from local date-time to zoned, not null
Returns:: the zoned date-time, not null
Throws:: IllegalCalendarFieldValueException - if the value of any field is out of range; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year; CalendricalException - if the resolver cannot resolve an invalid local date-time

of

public static ZonedDateTime of(LocalDate date,
                               LocalTime time,
                               ZoneId zone)

Obtains an instance of 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.

Parameters:: date - the local date, not null; time - the local time, not null; zone - the time-zone, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if the local date-time is invalid for the time-zone

of

public static ZonedDateTime of(LocalDate date,
                               LocalTime time,
                               ZoneId zone,
                               ZoneResolver resolver)

Obtains an instance of 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.

Parameters:: date - the local date, not null; time - the local time, not null; zone - the time-zone, not null; resolver - the resolver from local date-time to zoned, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if the resolver cannot resolve an invalid local date-time

of

public static ZonedDateTime of(LocalDateTime dateTime,
                               ZoneId zone)

Obtains an instance of 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.

Parameters:: dateTime - the local date-time, not null; zone - the time-zone, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if the local date-time is invalid for the time-zone

of

public static ZonedDateTime of(LocalDateTime dateTime,
                               ZoneId zone,
                               ZoneResolver resolver)

Obtains an instance of 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.

Parameters:: dateTime - the local date-time, not null; zone - the time-zone, not null; resolver - the resolver from local date-time to zoned, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if the resolver cannot resolve an invalid local date-time

of

public static ZonedDateTime of(OffsetDateTime dateTime,
                               ZoneId zone)

Obtains an instance of 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(javax.time.InstantProvider, javax.time.calendar.ZoneId). This method will retain the date and time and throw an exception if the offset is invalid. The ofInstant method will change the date and time if necessary to retain the same instant.

Parameters:: dateTime - the offset date-time to use, not null; zone - the time-zone, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if no rules can be found for the zone; CalendricalException - if the date-time is invalid due to a gap in the local time-line; CalendricalException - if the offset is invalid for the time-zone at the date-time

ofInstantUTC

public static ZonedDateTime ofInstantUTC(InstantProvider instantProvider)

Obtains an instance of ZonedDateTime from an InstantProvider using the UTC zone.

This factory creates a ZonedDateTime from an instant using the UTC time-zone. If the instant represents a point on the time-line outside the supported year range then an exception will be thrown.

Parameters:: instantProvider - the instant to convert, not null
Returns:: the zoned date-time in UTC, not null
Throws:: CalendricalException - if the result exceeds the supported range

ofInstant

public static ZonedDateTime ofInstant(InstantProvider instantProvider,
                                      ZoneId zone)

Obtains an instance of ZonedDateTime from an InstantProvider.

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.

If an OffsetDateTime is passed in then it will effectively be converted to an Instant in order to calculate the correct offset for the zone. This can change the local date and time. Use of(OffsetDateTime, ZoneId) if you want to guarantee the same local date-time.

Parameters:: instantProvider - the instant to convert, not null; zone - the time-zone, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if the result exceeds the supported range

ofEpochSecond

public static ZonedDateTime ofEpochSecond(long epochSecond,
                                          ZoneId zone)

Obtains an instance of ZonedDateTime using seconds from the epoch of 1970-01-01T00:00:00Z.

The nanosecond field is set to zero.

Parameters:: epochSecond - the number of seconds from the epoch of 1970-01-01T00:00:00Z; zone - the time-zone, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if the result exceeds the supported range

from

public static ZonedDateTime from(Calendrical... calendricals)

Obtains an instance of ZonedDateTime from a set of calendricals.

A calendrical represents some form of date and time information. This method combines the input calendricals into a date-time.

Parameters:: calendricals - the calendricals to create a date-time from, no nulls, not null
Returns:: the zoned date-time, not null
Throws:: CalendricalException - if unable to merge to a zoned date-time

parse

public static ZonedDateTime parse(java.lang.CharSequence text)

Obtains an instance of ZonedDateTime from a text string such as 2007-12-03T10:15:30+01:00[Europe/Paris].

The string must represent a valid date-time and is parsed using DateTimeFormatters.isoZonedDateTime(). Year, month, day-of-month, hour, minute, offset and zone are required. Seconds and fractional seconds are optional. Years outside the range 0000 to 9999 must be prefixed by the plus or minus symbol.

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, not null
Throws:: CalendricalParseException - if the text cannot be parsed

parse

public static ZonedDateTime parse(java.lang.CharSequence text,
                                  DateTimeFormatter formatter)

Obtains an instance of ZonedDateTime 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 null; formatter - the formatter to use, not null
Returns:: the parsed zoned date-time, not null
Throws:: java.lang.UnsupportedOperationException - if the formatter cannot parse; CalendricalParseException - if the text cannot be parsed

get

public <T> T get(CalendricalRule<T> ruleToDerive)

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 interface Calendrical

Parameters:: ruleToDerive - the rule to derive, not null
Returns:: the value for the rule, null if the value cannot be returned

getOffset

public ZoneOffset getOffset()

Gets the zone offset, such as '+01:00'.

Returns:: the zone offset, not 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, not null
Throws:: CalendricalException - if no rules can be found for the zone; CalendricalException - 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.

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, not null
Throws:: CalendricalException - if no rules can be found for the zone; CalendricalException - if no rules are valid for this date-time

getZone

public ZoneId 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. The getApplicableRules() method will resolve the actual zone-rules.

Returns:: the time-zone, not null

withZoneSameLocal

public ZonedDateTime withZoneSameLocal(ZoneId 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(ZoneId).

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, not null

withZoneSameLocal

public ZonedDateTime withZoneSameLocal(ZoneId 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(ZoneId).

This instance is immutable and unaffected by this method call.

Parameters:: zone - the time-zone to change to, not null; resolver - the resolver to use, not null
Returns:: a ZonedDateTime based on this date-time with the requested zone, not null

withZoneSameInstant

public ZonedDateTime withZoneSameInstant(ZoneId 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(ZoneId).

Parameters:: zone - the time-zone to change to, not null
Returns:: a ZonedDateTime based on this date-time with the requested zone, not null
Throws:: CalendricalException - if the result exceeds the supported date range

getApplicableZone

public ZoneId 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, not null
Throws:: CalendricalException - if no rules can be found for the zone; CalendricalException - 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 ZoneId.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, not null
Throws:: CalendricalException - if no rules can be found for the zone; CalendricalException - 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 a Year.

Returns:: the year, from MIN_YEAR to MAX_YEAR

getMonthOfYear

public MonthOfYear getMonthOfYear()

Gets the month-of-year field, which is an enum 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.

Returns:: the month-of-year, not 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 enum 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.

Returns:: the day-of-week, not 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 ISO-8601 standard.

Returns:: true if the year is leap, false otherwise

withDateTime

public ZonedDateTime withDateTime(LocalDateTime dateTime)

Returns a copy of this ZonedDateTime with the local date-time altered.

This method returns an object with the same ZoneId and the specified LocalDateTime.

If the adjusted date results in a date-time that is invalid, then the ZoneResolvers.retainOffset() resolver is used.

Parameters:: dateTime - the local date-time to change to, not null
Returns:: a ZonedDateTime based on this time with the requested date-time, not null

withDateTime

public ZonedDateTime withDateTime(LocalDateTime dateTime,
                                  ZoneResolver resolver)

Returns a copy of this ZonedDateTime with the local date-time altered, providing a resolver for invalid date-times.

This method returns an object with the same ZoneId and the specified LocalDateTime.

If the adjusted date results in a date-time that is invalid, then the specified resolver is used.

Parameters:: dateTime - the local date-time to change to, not null; resolver - the resolver to use, not null
Returns:: a ZonedDateTime based on this time with the requested date-time, not null

with

public ZonedDateTime with(DateAdjuster adjuster)

Returns a copy of this ZonedDateTime with the date altered using the adjuster.

This adjusts the date according to the rules of the specified adjuster. The time, offset and zone are not part of the calculation. Note that LocalDate implements DateAdjuster, thus this method can be used to change the entire date.

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, not null

with

public ZonedDateTime with(DateAdjuster adjuster,
                          ZoneResolver resolver)

Returns a copy of this ZonedDateTime with the date altered using the adjuster, providing a resolver for invalid date-times.

If the adjusted date results in a date-time that is invalid, then the specified resolver is used.

This instance is immutable and unaffected by this method call.

Parameters:: adjuster - the adjuster to use, not null; resolver - the resolver to use, not null
Returns:: a ZonedDateTime based on this date-time with the date adjusted, not null
Throws:: CalendricalException - if the date-time cannot be resolved

with

public ZonedDateTime with(TimeAdjuster adjuster)

Returns a copy of this ZonedDateTime with the time altered using the adjuster.

This adjusts the time according to the rules of the specified adjuster. The date, offset and zone are not part of the calculation. Note that LocalTime implements TimeAdjuster, thus this method can be used to change the entire time.

If the adjusted time 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, not null

with

public ZonedDateTime with(TimeAdjuster adjuster,
                          ZoneResolver resolver)

Returns a copy of this ZonedDateTime with the time altered using the adjuster, providing a resolver for invalid date-times.

If the adjusted time results in a date-time that is invalid, then the specified resolver is used.

This instance is immutable and unaffected by this method call.

Parameters:: adjuster - the adjuster to use, not null; resolver - the resolver to use, not null
Returns:: a ZonedDateTime based on this date-time with the time adjusted, not null
Throws:: CalendricalException - if the date-time cannot be resolved

withYear

public ZonedDateTime withYear(int year)

Returns a copy of this ZonedDateTime with the year value altered.

If the resulting day for the year is invalid, it will be resolved using DateResolvers.previousValid(). If the adjustment results in a date-time that is invalid for the zone, 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, not null
Throws:: IllegalCalendarFieldValueException - if the year value is invalid

with

public ZonedDateTime with(MonthOfYear monthOfYear)

Returns a copy of this ZonedDateTime with the month-of-year value altered.

If the resulting day for the month is invalid, it will be resolved using DateResolvers.previousValid(). If the adjustment results in a date-time that is invalid for the zone, 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, not null
Returns:: a ZonedDateTime based on this date-time with the requested month, not null

withMonthOfYear

public ZonedDateTime withMonthOfYear(int monthOfYear)

Returns a copy of this ZonedDateTime with the month-of-year value altered.

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, not null
Throws:: IllegalCalendarFieldValueException - if the month value is invalid

withDayOfMonth

public ZonedDateTime withDayOfMonth(int dayOfMonth)

Returns a copy of this 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.

Parameters:: dayOfMonth - the day-of-month to represent, from 1 to 31
Returns:: a ZonedDateTime based on this date-time with the requested day, not null
Throws:: IllegalCalendarFieldValueException - if the day-of-month value is invalid; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year

withDayOfYear

public ZonedDateTime withDayOfYear(int dayOfYear)

Returns a copy of this 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.

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, not null
Throws:: IllegalCalendarFieldValueException - if the day-of-year value is invalid; InvalidCalendarFieldException - if the day-of-year is invalid for the year

withDate

public ZonedDateTime withDate(int year,
                              int monthOfYear,
                              int dayOfMonth)

Returns a copy of this 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.

Parameters:: year - the year to represent, from MIN_YEAR to MAX_YEAR; monthOfYear - 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, not null
Throws:: IllegalCalendarFieldValueException - if the any field value is invalid; InvalidCalendarFieldException - if the day-of-month is invalid for the month-year

withHourOfDay

public ZonedDateTime withHourOfDay(int hourOfDay)

Returns a copy of this 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.

Parameters:: hourOfDay - the hour-of-day to represent, from 0 to 23
Returns:: a ZonedDateTime based on this date-time with the requested hour, not null
Throws:: IllegalCalendarFieldValueException - if the hour value is invalid

withMinuteOfHour

public ZonedDateTime withMinuteOfHour(int minuteOfHour)

Returns a copy of this 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.

Parameters:: minuteOfHour - the minute-of-hour to represent, from 0 to 59
Returns:: a ZonedDateTime based on this date-time with the requested minute, not null
Throws:: IllegalCalendarFieldValueException - if the minute value is invalid

withSecondOfMinute

public ZonedDateTime withSecondOfMinute(int secondOfMinute)

Returns a copy of this 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.

Parameters:: secondOfMinute - the second-of-minute to represent, from 0 to 59
Returns:: a ZonedDateTime based on this date-time with the requested second, not null
Throws:: IllegalCalendarFieldValueException - if the second value is invalid

withNanoOfSecond

public ZonedDateTime withNanoOfSecond(int nanoOfSecond)

Returns a copy of this 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.

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, not null
Throws:: IllegalCalendarFieldValueException - if the nanos value is invalid

withTime

public ZonedDateTime withTime(int hourOfDay,
                              int minuteOfHour)

Returns a copy of this 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.

Parameters:: hourOfDay - the hour-of-day to represent, from 0 to 23; minuteOfHour - the minute-of-hour to represent, from 0 to 59
Returns:: a ZonedDateTime based on this date-time with the requested time, not null
Throws:: IllegalCalendarFieldValueException - if any field value is invalid

withTime

public ZonedDateTime withTime(int hourOfDay,
                              int minuteOfHour,
                              int secondOfMinute)

Returns a copy of this 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.

Parameters:: hourOfDay - the hour-of-day to represent, from 0 to 23; minuteOfHour - the minute-of-hour to represent, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59
Returns:: a ZonedDateTime based on this date-time with the requested time, not 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 this 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.

Parameters:: hourOfDay - the hour-of-day to represent, from 0 to 23; minuteOfHour - the minute-of-hour to represent, from 0 to 59; secondOfMinute - the second-of-minute to represent, from 0 to 59; nanoOfSecond - the nano-of-second to represent, from 0 to 999,999,999
Returns:: a ZonedDateTime based on this date-time with the requested time, not null
Throws:: IllegalCalendarFieldValueException - if any field value is invalid

plus

public ZonedDateTime plus(PeriodProvider periodProvider)

Returns a copy of this 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.

Parameters:: periodProvider - the period to add, not null
Returns:: a ZonedDateTime based on this date-time with the period added, not null
Throws:: CalendricalException - if the specified period cannot be converted to a Period; CalendricalException - if the result exceeds the supported range

plus

public ZonedDateTime plus(PeriodProvider periodProvider,
                          ZoneResolver resolver)

Returns a copy of this 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.

Parameters:: periodProvider - the period to add, not null
Returns:: a ZonedDateTime based on this date-time with the period added, not null
Throws:: CalendricalException - if the specified period cannot be converted to a Period; CalendricalException - if the result exceeds the supported range

plusYears

public ZonedDateTime plusYears(long years)

Returns a copy of this ZonedDateTime 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, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusMonths

public ZonedDateTime plusMonths(long months)

Returns a copy of this ZonedDateTime 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, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusWeeks

public ZonedDateTime plusWeeks(long weeks)

Returns a copy of this 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.

Parameters:: weeks - the weeks to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the weeks added, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusDays

public ZonedDateTime plusDays(long days)

Returns a copy of this 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.

Parameters:: days - the days to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the days added, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusHours

public ZonedDateTime plusHours(long hours)

Returns a copy of this 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.

Parameters:: hours - the hours to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the hours added, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusMinutes

public ZonedDateTime plusMinutes(long minutes)

Returns a copy of this 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.

Parameters:: minutes - the minutes to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the minutes added, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusSeconds

public ZonedDateTime plusSeconds(long seconds)

Returns a copy of this 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.

Parameters:: seconds - the seconds to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the seconds added, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusNanos

public ZonedDateTime plusNanos(long nanos)

Returns a copy of this 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.

Parameters:: nanos - the nanos to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the nanoseconds added, not null
Throws:: CalendricalException - if the result exceeds the supported range

plusDuration

public ZonedDateTime plusDuration(PeriodProvider periodProvider)

Returns a copy of this 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.

Parameters:: periodProvider - the period to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the duration added, not null
Throws:: java.lang.ArithmeticException - if the calculation exceeds the capacity of Instant; CalendricalException - if the result exceeds the supported range

plusDuration

public ZonedDateTime plusDuration(Duration duration)

Returns a copy of this 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.

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, not 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 this ZonedDateTime with the specified duration added.

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 negative; minutes - the minutes to add, positive or negative; seconds - the seconds to add, positive or negative; nanos - the nanos to add, positive or negative
Returns:: a ZonedDateTime based on this date-time with the duration added, not null
Throws:: java.lang.ArithmeticException - if the calculation exceeds the capacity of Instant; CalendricalException - if the result exceeds the supported range

minus

public ZonedDateTime minus(PeriodProvider periodProvider)

Returns a copy of this 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.

Parameters:: periodProvider - the period to subtract, not null
Returns:: a ZonedDateTime based on this date-time with the period subtracted, not null
Throws:: CalendricalException - if the specified period cannot be converted to a Period; CalendricalException - if the result exceeds the supported range

minus

public ZonedDateTime minus(PeriodProvider periodProvider,
                           ZoneResolver resolver)

Returns a copy of this 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.

Parameters:: periodProvider - the period to subtract, not null
Returns:: a ZonedDateTime based on this date-time with the period subtracted, not null
Throws:: CalendricalException - if the specified period cannot be converted to a Period; CalendricalException - if the result exceeds the supported range

minusYears

public ZonedDateTime minusYears(long years)

Returns a copy of this ZonedDateTime 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, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusMonths

public ZonedDateTime minusMonths(long months)

Returns a copy of this ZonedDateTime 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, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusWeeks

public ZonedDateTime minusWeeks(long weeks)

Returns a copy of this 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.

Parameters:: weeks - the weeks to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the weeks subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusDays

public ZonedDateTime minusDays(long days)

Returns a copy of this 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.

Parameters:: days - the days to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the days subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusHours

public ZonedDateTime minusHours(long hours)

Returns a copy of this 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.

Parameters:: hours - the hours to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the hours subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusMinutes

public ZonedDateTime minusMinutes(long minutes)

Returns a copy of this 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.

Parameters:: minutes - the minutes to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the minutes subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusSeconds

public ZonedDateTime minusSeconds(long seconds)

Returns a copy of this 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.

Parameters:: seconds - the seconds to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the seconds subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusNanos

public ZonedDateTime minusNanos(long nanos)

Returns a copy of this 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.

Parameters:: nanos - the nanos to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the nanoseconds subtracted, not null
Throws:: CalendricalException - if the result exceeds the supported range

minusDuration

public ZonedDateTime minusDuration(PeriodProvider periodProvider)

Returns a copy of this 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.

Parameters:: periodProvider - the period to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the duration subtracted, not null
Throws:: java.lang.ArithmeticException - if the calculation exceeds the capacity of Instant; CalendricalException - if the result exceeds the supported range

minusDuration

public ZonedDateTime minusDuration(Duration duration)

Returns a copy of this 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.

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, not 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 this ZonedDateTime with the specified duration subtracted.

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 negative; minutes - the minutes to subtract, positive or negative; seconds - the seconds to subtract, positive or negative; nanos - the nanos to subtract, positive or negative
Returns:: a ZonedDateTime based on this date-time with the duration subtracted, not null
Throws:: java.lang.ArithmeticException - if the calculation exceeds the capacity of Instant; CalendricalException - if the result exceeds the supported range

matches

public boolean matches(CalendricalMatcher matcher)

Checks whether this 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.

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 use matches(javax.time.calendar.CalendricalMatcher) rather than this method.

Specified by:: matchesCalendrical in interface CalendricalMatcher

Parameters:: calendrical - the calendrical to match, not null
Returns:: true if the calendrical matches, false otherwise

toInstant

public Instant toInstant()

Converts this ZonedDateTime to an Instant.

Specified by:: toInstant in interface InstantProvider

Returns:: an Instant representing the same instant, not null

toLocalDate

public LocalDate toLocalDate()

Converts this ZonedDateTime to a LocalDate.

Returns:: a LocalDate representing the date fields of this date-time, not null

toLocalTime

public LocalTime toLocalTime()

Converts this ZonedDateTime to a LocalTime.

Returns:: a LocalTime representing the time fields of this date-time, not null

toLocalDateTime

public LocalDateTime toLocalDateTime()

Converts this ZonedDateTime to a LocalDateTime.

Returns:: a LocalDateTime representing the fields of this date-time, not null

toOffsetDate

public OffsetDate toOffsetDate()

Converts this ZonedDateTime to a OffsetDate.

Returns:: a OffsetDate representing the date fields of this date-time, not null

toOffsetTime

public OffsetTime toOffsetTime()

Converts this ZonedDateTime to a OffsetTime.

Returns:: a OffsetTime representing the time fields of this date-time, not null

toOffsetDateTime

public OffsetDateTime toOffsetDateTime()

Converts this ZonedDateTime to a OffsetDateTime.

Returns:: a OffsetDateTime representing the fields of this date-time, not null

toEpochSecond

public long toEpochSecond()

Converts this 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.

Returns:: the number of seconds from the epoch of 1970-01-01T00:00:00Z

compareTo

public int compareTo(ZonedDateTime other)

Compares this 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.

Specified by:: compareTo in interface java.lang.Comparable<ZonedDateTime>

Parameters:: other - the other date-time to compare to, not null
Returns:: the comparator value, negative if less, positive if greater
Throws:: java.lang.NullPointerException - if other 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 using dateTime1.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:: java.lang.NullPointerException - if other is null

isAfter

public boolean isAfter(ZonedDateTime other)

Checks if the instant of this date-time is after that of the specified date-time.

Parameters:: other - the other date-time to compare to, not null
Returns:: true if this is after the specified date-time
Throws:: java.lang.NullPointerException - if other 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) 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());.

Parameters:: other - the other date-time to compare to, not null
Returns:: true if this is after the specified date-time
Throws:: java.lang.NullPointerException - if other is null

equals

public boolean equals(java.lang.Object obj)

Checks if this date-time is equal to another date-time.

The comparison is based on the offset date-time and the zone. To compare for the same instant on the time-line, use equalInstant(javax.time.calendar.ZonedDateTime).

Overrides:: equals in class java.lang.Object

Parameters:: obj - the object to check, null returns false
Returns:: true if this is equal to the other date-time

hashCode

public int hashCode()

A hash code for this date-time.

Overrides:: hashCode in class java.lang.Object

Returns:: a suitable hash code

toString

public java.lang.String toString()

Outputs this date-time as a 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:mmXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnnnnXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnnnnnnnXXXXX'['I']'

The format used will be the shortest that outputs the full value of the time where the omitted parts are implied to be zero.

Overrides:: toString in class java.lang.Object

Returns:: a string representation of this date-time, not null

toString

public java.lang.String toString(DateTimeFormatter formatter)

Outputs this date-time as a String using the formatter.

Parameters:: formatter - the formatter to use, not null
Returns:: the formatted date-time string, not null
Throws:: java.lang.UnsupportedOperationException - if the formatter cannot print; CalendricalException - if an error occurs during printing

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.time.calendar Class ZonedDateTime

rule

now

now

of

of

of

of

of

of

of

of

of

ofInstantUTC

ofInstant

ofEpochSecond

from

parse

parse

get

getOffset

withEarlierOffsetAtOverlap

withLaterOffsetAtOverlap

getZone

withZoneSameLocal

withZoneSameLocal

withZoneSameInstant

getApplicableZone

getApplicableRules

getYear

getMonthOfYear

getDayOfMonth

getDayOfYear

getDayOfWeek

getHourOfDay

getMinuteOfHour

getSecondOfMinute

getNanoOfSecond

isLeapYear

withDateTime

withDateTime

with

with

with

with

withYear

with

withMonthOfYear

withDayOfMonth

withDayOfYear

withDate

withHourOfDay

withMinuteOfHour

withSecondOfMinute

withNanoOfSecond

withTime

withTime

withTime

plus

plus

plusYears

plusMonths

plusWeeks

plusDays

plusHours

plusMinutes

plusSeconds

plusNanos

plusDuration

plusDuration

plusDuration

minus

minus

minusYears

minusMonths

minusWeeks

minusDays

minusHours

minusMinutes

minusSeconds

javax.time.calendar
Class ZonedDateTime