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,
and a time-zone, with a zone offset used to handle ambiguous local date-times.
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.
This class handles conversion from the local time-line of LocalDateTime
to the instant time-line of Instant.
The difference between the two time-lines is the offset from UTC/Greenwich,
represented by a ZoneOffset.
Converting between the two time-lines involves calculating the offset using the
rules accessed from the ZoneId.
Obtaining the offset for an instant is simple, as there is exactly one valid
offset for each instant. By contrast, obtaining the offset for a local date-time
is not straightforward. There are three cases:
Any method that converts directly or implicitly from a local date-time to an instant by obtaining the offset has the potential to be complicated.
For Gaps, the general strategy is that if the local date-time falls in the middle of a Gap, then the resulting zoned date-time will have a local date-time shifted forwards by the length of the Gap, resulting in a date-time in the later offset, typically "summer" time.
For Overlaps, the general strategy is that if the local date-time falls in the
middle of an Overlap, then the previous offset will be retained. If there is no
previous offset, or the previous offset is invalid, then the earlier offset is
used, typically "summer" time. Two additional methods,
withEarlierOffsetAtOverlap() and withLaterOffsetAtOverlap(),
help manage the case of an overlap.
In terms of design, this class should be viewed primarily as the combination
of a LocalDateTime and a ZoneId. The ZoneOffset is
a vital, but secondary, piece of information, used to ensure that the class
represents an instant, especially during a daylight savings overlap.
This is a value-based
class; programmers should treat instances that are
equal as interchangeable and should not
use instances for synchronization, or unpredictable behavior may
occur. For example, in a future release, synchronization may fail.
The equals method should be used for comparisons.
Implementation Specification
A ZonedDateTime holds state equivalent to three separate objects,
a LocalDateTime, a ZoneId and the resolved ZoneOffset.
The offset and local date-time are used to define an instant when necessary.
The zone ID is used to obtain the rules for how and when the offset changes.
The offset cannot be freely set, as the zone controls which offsets are valid.
This class is immutable and thread-safe.
| Modifier and Type | Field and Description |
|---|---|
| private final LocalDateTime | |
| private final ZoneOffset | |
| private static final long | serialVersionUID
Serialization version. |
| private final ZoneId |
| Access | Constructor and Description |
|---|---|
| private | ZonedDateTime(LocalDateTime
the date-time, validated as not null dateTime, ZoneOffset the zone offset, validated as not null offset, ZoneId the time-zone, validated as not null zone)Constructor. |
| Modifier and Type | Method and Description |
|---|---|
| private static ZonedDateTime | Returns: the zoned date-time, not nullthe number of seconds from the epoch of 1970-01-01T00:00:00Z epochSecond, int the nanosecond within the second, from 0 to 999,999,999 nanoOfSecond, ZoneId the time-zone, not null zone)Obtains an instance of |
| public boolean | Returns: true if this is equal to the other date-timethe object to check, null returns false obj)Overrides java. Implements java. Checks if this date-time is equal to another date-time. |
| public String | Returns: the formatted date-time string, not nullthe formatter to use, not null formatter)Overrides default java. Formats this date-time using the specified formatter. |
| public static ZonedDateTime | Returns: the zoned date-time, not nullthe temporal object to convert, not null temporal)Hides java. Obtains an instance of |
| public int | Returns: the value for the fieldthe field to get, not null field)Overrides default java. Gets the value of the specified field from this date-time as an |
| public int | |
| public DayOfWeek | Returns: the day-of-week, not nullGets the day-of-week field, which is an enum |
| public int | Returns: the day-of-year, from 1 to 365, or 366 in a leap yearGets the day-of-year field. |
| public int | |
| public long | Returns: the value for the fieldthe field to get, not null field)Overrides default java. Implements java. Gets the value of the specified field from this date-time as a |
| public int | |
| public Month | |
| public int | |
| public int | |
| public ZoneOffset | Returns: the zone offset, not nullImplements java. Gets the zone offset, such as '+01:00'. |
| public int | |
| public int | |
| public ZoneId | Returns: the time-zone, not nullImplements java. Gets the time-zone, such as 'Europe/Paris'. |
| public int | Returns: a suitable hash codeOverrides java. Implements java. A hash code for this date-time. |
| public boolean | Returns: true if the field is supported on this date-time, false if notthe field to check, null returns false field)Implements java. Checks if the specified field is supported. |
| public boolean | Returns: true if the unit can be added/subtracted, false if notthe unit to check, null returns false unit)Overrides default java. Implements java. Checks if the specified unit is supported. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the subtraction made, not nullthe amount to subtract, not null amountToSubtract)Overrides default java. Returns a copy of this date-time with the specified amount subtracted. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the specified amount subtracted, not nullthe amount of the unit to subtract from the result, may be negative amountToSubtract, TemporalUnit the unit of the amount to subtract, not null unit)Overrides default java. Returns a copy of this date-time with the specified amount subtracted. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the days subtracted, not nullthe days to subtract, may be negative days)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the hours subtracted, not nullthe hours to subtract, may be negative hours)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the minutes subtracted, not nullthe minutes to subtract, may be negative minutes)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the months subtracted, not nullthe months to subtract, may be negative months)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the nanoseconds subtracted, not nullthe nanos to subtract, may be negative nanos)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the seconds subtracted, not nullthe seconds to subtract, may be negative seconds)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the weeks subtracted, not nullthe weeks to subtract, may be negative weeks)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the years subtracted, not nullthe years to subtract, may be negative years)Returns a copy of this |
| public static ZonedDateTime | Returns: the current date-time using the system clock, not nullObtains the current date-time from the system clock in the default time-zone. |
| public static ZonedDateTime | |
| public static ZonedDateTime | |
| public static ZonedDateTime | |
| public static ZonedDateTime | Returns: the zoned date-time, not nullthe local date-time, not null localDateTime, ZoneId the time-zone, not null zone)Obtains an instance of |
| public static ZonedDateTime | Returns: the zoned date-time, not nullthe year to represent, from MIN_YEAR to MAX_YEAR year, int the month-of-year to represent, from 1 (January) to 12 (December) month, int the day-of-month to represent, from 1 to 31 dayOfMonth, int the hour-of-day to represent, from 0 to 23 hour, int the minute-of-hour to represent, from 0 to 59 minute, int the second-of-minute to represent, from 0 to 59 second, int the nano-of-second to represent, from 0 to 999,999,999 nanoOfSecond, ZoneId the time-zone, not null zone)Obtains an instance of |
| public static ZonedDateTime | |
| public static ZonedDateTime | Returns: the zoned date-time, not nullthe local date-time, not null localDateTime, ZoneOffset the zone offset, not null offset, ZoneId the time-zone, not null zone)Obtains an instance of |
| private static ZonedDateTime | Returns: the zoned date-time, not nullthe local date-time, not null localDateTime, ZoneOffset the zone offset, not null offset, ZoneId the time-zone, not null zone)Obtains an instance of This creates a zoned date-time with no checks other than no nulls. |
| public static ZonedDateTime | Returns: the zoned date-time, not nullthe local date-time, not null localDateTime, ZoneId the time-zone, not null zone, ZoneOffset the zone offset, null if no preference preferredOffset)Obtains an instance of |
| public static ZonedDateTime | Returns: the zoned date-time, not nullthe local date-time, not null localDateTime, ZoneOffset the zone offset, not null offset, ZoneId the time-zone, not null zone)Obtains an instance of This creates a zoned date-time ensuring that the offset is valid for the local date-time according to the rules of the specified zone. |
| public static ZonedDateTime | Returns: the parsed zoned date-time, not nullthe text to parse such as "2007-12-03T10:15:30+01:00[Europe/Paris]", not null text)Obtains an instance of |
| public static ZonedDateTime | Returns: the parsed zoned date-time, not nullthe text to parse, not null text, DateTimeFormatter the formatter to use, not null formatter)Obtains an instance of |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the addition made, not nullthe amount to add, not null amountToAdd)Overrides default java. Returns a copy of this date-time with the specified amount added. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the specified amount added, not nullthe amount of the unit to add to the result, may be negative amountToAdd, TemporalUnit the unit of the amount to add, not null unit)Implements java. Returns a copy of this date-time with the specified amount added. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the days added, not nullthe days to add, may be negative days)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the hours added, not nullthe hours to add, may be negative hours)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the minutes added, not nullthe minutes to add, may be negative minutes)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the months added, not nullthe months to add, may be negative months)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the nanoseconds added, not nullthe nanos to add, may be negative nanos)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the seconds added, not nullthe seconds to add, may be negative seconds)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the weeks added, not nullthe weeks to add, may be negative weeks)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the years added, not nullthe years to add, may be negative years)Returns a copy of this |
| public < the type of the result R> R | Returns: the query result, null may be returned (defined by the query)the query to invoke, not null query)Overrides default java. Queries this date-time using the specified query. |
| public ValueRange | Returns: the range of valid values for the field, not nullthe field to query the range for, not null field)Overrides default java. Gets the range of valid values for the specified field. |
| pack-priv static ZonedDateTime | |
| private void | |
| private ZonedDateTime | Returns: the zoned date-time, not nullthe new local date-time, not null newDateTime)Resolves the new local date-time using the offset to identify the instant. |
| private ZonedDateTime | Returns: the zoned date-time, not nullthe new local date-time, not null newDateTime)Resolves the new local date-time using this zone ID, retaining the offset if possible. |
| private ZonedDateTime | Returns: the zoned date-time, not nullthe offset, not null offset)Resolves the offset into this zoned date-time for the with methods. |
| public LocalDate | Returns: the date part of this date-time, not nullOverrides default java. Gets the |
| public LocalDateTime | Returns: the local date-time part of this date-time, not nullImplements java. Gets the |
| public LocalTime | Returns: the time part of this date-time, not nullOverrides default java. Gets the |
| public OffsetDateTime | Returns: an offset date-time representing the same local date-time and offset, not nullConverts this date-time to an |
| public String | Returns: a string representation of this date-time, not nullOverrides java. Implements java. Outputs this date-time as a |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the time truncated, not nullthe unit to truncate to, not null unit)Returns a copy of this |
| public long | Returns: the amount of time between this date-time and the end date-timethe end date, exclusive, which is converted to a endExclusive, TemporalUnit ZonedDateTime, not nullthe unit to measure the amount in, not null unit)Implements java. Calculates the amount of time until another date-time in terms of the specified unit. |
| public ZonedDateTime | Returns: aZonedDateTime based on this with the adjustment made, not nullthe adjuster to use, not null adjuster)Overrides default java. Returns an adjusted copy of this date-time. |
| public ZonedDateTime | Returns: aZonedDateTime based on this with the specified field set, not nullthe field to set in the result, not null field, long the new value of the field in the result newValue)Implements java. Returns a copy of this date-time with the specified field set to a new value. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested day, not nullthe day-of-month to set in the result, from 1 to 28-31 dayOfMonth)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date with the requested day, not nullthe day-of-year to set in the result, from 1 to 365-366 dayOfYear)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the earlier offset, not nullImplements java. Returns a copy of this date-time changing the zone offset to the earlier of the two valid offsets at a local time-line overlap. |
| public ZonedDateTime | Returns: aZonedDateTime with the zone ID set to the offset, not nullReturns a copy of this date-time with the zone ID set to the offset. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested hour, not nullthe hour-of-day to set in the result, from 0 to 23 hour)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the later offset, not nullImplements java. Returns a copy of this date-time changing the zone offset to the later of the two valid offsets at a local time-line overlap. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested minute, not nullthe minute-of-hour to set in the result, from 0 to 59 minute)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested month, not nullthe month-of-year to set in the result, from 1 (January) to 12 (December) month)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested nanosecond, not nullthe nano-of-second to set in the result, from 0 to 999,999,999 nanoOfSecond)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested second, not nullthe second-of-minute to set in the result, from 0 to 59 second)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested year, not nullthe year to set in the result, from MIN_YEAR to MAX_YEAR year)Returns a copy of this |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested zone, not nullthe time-zone to change to, not null zone)Implements java. Returns a copy of this date-time with a different time-zone, retaining the instant. |
| public ZonedDateTime | Returns: aZonedDateTime based on this date-time with the requested zone, not nullthe time-zone to change to, not null zone)Implements java. Returns a copy of this date-time with a different time-zone, retaining the local date-time if possible. |
| pack-priv void | |
| private Object | Returns: the instance ofSer, not nullWrites the object using a dedicated serialized form. |