ZonedDateTime class

A LocalDateTime in a specific time zone and with a particular offset to distinguish between otherwise-ambiguous instants. A ZonedDateTime is global, in that it maps to a single Instant.

Although ZonedDateTime includes both local and global concepts, it only supports duration-based - and not calendar-based - arithmetic. This avoids ambiguities and skipped date/time values becoming a problem within a series of calculations; instead, these can be considered just once, at the point of conversion to a ZonedDateTime.

ZonedDateTime does not implement ordered comparison operators, as there is no obvious natural ordering that works in all cases. Equality is supported however, requiring equality of zone, calendar and date/time. If you want to sort ZonedDateTime values, you should explicitly choose one of the orderings provided via the static properties in the ZonedDateTimeComparer class (or implement your own comparison).

Annotations

@immutable

Constructors

ZonedDateTime([Instant instant = Instant.unixEpoch, DateTimeZone? zone, CalendarSystem? calendar]): Initializes a new instance of ZonedDateTime in the specified time zone and the ISO or specified calendar.
factory
ZonedDateTime.atLeniently(LocalDateTime localDateTime, DateTimeZone zone): Maps the given LocalDateTime to the corresponding ZonedDateTime in a lenient manner: ambiguous values map to the earlier of the alternatives, and 'skipped' values are shifted forward by the duration of the 'gap'.
factory
ZonedDateTime.atOffset(LocalDateTime localDateTime, DateTimeZone zone, Offset offset): Initializes a new instance of ZonedDateTime in the specified time zone from a given local time and offset. The offset is validated to be correct as part of initialization. In most cases a local time can only map to a single instant anyway, but the offset is included here for cases where the local time is ambiguous, usually due to daylight saving transitions.
factory
ZonedDateTime.atStartOfDay(LocalDate date, DateTimeZone zone): Returns the earliest valid ZonedDateTime with the given local date.
factory
ZonedDateTime.atStrictly(LocalDateTime localDateTime, DateTimeZone zone): Maps the given LocalDateTime to the corresponding ZonedDateTime, if and only if that mapping is unambiguous in this time zone. Otherwise, SkippedTimeError or AmbiguousTimeException is thrown, depending on whether the mapping is ambiguous or the local date/time is skipped entirely.
factory
ZonedDateTime.resolve(LocalDateTime localDateTime, DateTimeZone zone, ZoneLocalMappingResolver resolver): Maps the given LocalDateTime to the corresponding ZonedDateTime, following the given ZoneLocalMappingResolver to handle ambiguity and skipped times.
factory

Properties

calendar → CalendarSystem: Gets the calendar system associated with this zoned date and time.
no setter
calendarDate → LocalDate: Gets the local date represented by this zoned date and time.
no setter
clockTime → LocalTime: Gets the time portion of this zoned date and time.
no setter
dayOfMonth → int: Gets the day of this zoned date and time within the month.
no setter
dayOfWeek → DayOfWeek: Gets the week day of this zoned date and time expressed as an DayOfWeek value.
no setter
dayOfYear → int: Gets the day of this zoned date and time within the year.
no setter
era → Era: Gets the era for this zoned date and time.
no setter
hashCode → int: Computes the hash code for this instance.
no setteroverride
hourOf12HourClock → int: Gets the hour of the half-day of this zoned date and time, in the range 1 to 12 inclusive.
no setter
hourOfDay → int: Gets the hour of day of this zoned date and time, in the range 0 to 23 inclusive.
no setter
localDateTime → LocalDateTime: Gets the time zone associated with this value. Gets the local date and time represented by this zoned date and time.
no setter
microsecondOfSecond → int: Gets the tick of this zoned date and time within the second, in the range 0 to 9,999,999 inclusive.
no setter
millisecondOfSecond → int: Gets the millisecond of this zoned date and time within the second, in the range 0 to 999 inclusive.
no setter
minuteOfHour → int: Gets the minute of this zoned date and time, in the range 0 to 59 inclusive.
no setter
monthOfYear → int: Gets the month of this zoned date and time within the year.
no setter
nanosecondOfSecond → int: Gets the nanosecond of this zoned date and time within the second, in the range 0 to 999,999,999 inclusive.
no setter
offset → Offset: Gets the offset of the local representation of this value from UTC.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
secondOfMinute → int: Gets the second of this zoned date and time within the minute, in the range 0 to 59 inclusive.
no setter
year → int: Gets the year of this zoned date and time. This returns the 'absolute year', so, for the ISO calendar, a value of 0 means 1 BC, for example.
no setter
yearOfEra → int: Gets the year of this zoned date and time within its era.
no setter
zone → DateTimeZone: Gets the time zone associated with this value.
final

Methods

add(Time time) → ZonedDateTime: Returns the result of adding a duration to this zoned date and time.
equals(ZonedDateTime other) → bool: Indicates whether the current object is equal to another object of the same type.
getZoneInterval() → ZoneInterval: Returns the ZoneInterval containing this value, in the time zone this value refers to.
isDaylightSavingTime() → bool: Indicates whether or not this ZonedDateTime is in daylight saving time for its time zone. This is determined by checking the ZoneInterval.savings property of the zone interval containing this value.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
subtract(Time time) → ZonedDateTime: Returns the result of subtracting a duration from this zoned date and time, for a fluent alternative to -.
timeSince(ZonedDateTime other) → Time: Returns the result of subtracting another zoned date and time from this one, resulting in the elapsed duration between the two instants represented by the values.
timeUntil(ZonedDateTime other) → Time: Returns the result of subtracting this from a zoned date and time, resulting in the elapsed duration between the two instants represented by the values.
toDateTimeLocal() → DateTime: Constructs a DateTime from this ZonedDateTime which has a DateTime.isUtc set to false and represents the same local time as this value rather than the same instant in time.
toDateTimeUtc() → DateTime: Constructs a DateTime from this ZonedDateTime which has a DateTime.isUtc set to true and represents the same instant of time as this value rather than the same local time.
toInstant() → Instant: Converts this value to the instant it represents on the time line.
toOffsetDateTime() → OffsetDateTime: Constructs an OffsetDateTime with the same local date and time, and the same offset as this zoned date and time, effectively just 'removing' the time zone itself.
toString([String? patternText, Culture? culture]) → String: Formats the value of the current instance using the specified pattern.
override
toStringDDC([String? patternText, Culture? culture]) → String
withCalendar(CalendarSystem calendar) → ZonedDateTime: Creates a new ZonedDateTime representing the same physical date, time and offset, but in a different calendar. The returned ZonedDateTime is likely to have different date field values to this one. For example, January 1st 1970 in the Gregorian calendar was December 19th 1969 in the Julian calendar.
withZone(DateTimeZone targetZone) → ZonedDateTime: Creates a new ZonedDateTime representing the same instant in time, in the same calendar but a different time zone.

Operators

operator +(Time time) → ZonedDateTime: Returns a new ZonedDateTime with the time advanced by the given duration. Note that due to daylight saving time changes this may not advance the local time by the same amount.
operator -(Time time) → ZonedDateTime: Returns a new ZonedDateTime with the duration subtracted. Note that due to daylight saving time changes this may not change the local time by the same amount.
operator ==(Object other) → bool: Implements the operator ==.
override

Static Methods

difference(ZonedDateTime end, ZonedDateTime start) → Time: Subtracts one zoned date and time from another, returning an elapsed duration.
minus(ZonedDateTime zonedDateTime, Time time) → ZonedDateTime: Subtracts a duration from a zoned date and time.
plus(ZonedDateTime zonedDateTime, Time time) → ZonedDateTime: Adds a duration to a zoned date and time.