DateTimeZone class abstract

Represents a time zone - a mapping between UTC and local time. A time zone maps UTC instants to local times

or, equivalently, to the offset from UTC at any particular instant.

The mapping is unambiguous in the 'UTC to local' direction, but the reverse is not true: when the offset changes, usually due to a Daylight Saving transition, the change either creates a gap (a period of local time which never occurs in the time zone) or an ambiguity (a period of local time which occurs twice in the time zone). Mapping back from local time to an instant requires consideration of how these problematic times will be handled.

// todo: move this? Time Machine provides various options when mapping local time to a specific instant:

atStrictly will throw an exception if the mapping from local time is either ambiguous or impossible, i.e. if there is anything other than one instant which maps to the given local time.
atLeniently will never throw an exception due to ambiguous or skipped times, resolving to the earlier option of ambiguous matches, or to a value that's forward-shifted by the duration of the gap for skipped times.
resolveLocal will apply a ZoneLocalMappingResolver to the result of a mapping.
mapLocal will return a ZoneLocalMapping with complete information about whether the given local time occurs zero times, once or twice. This is the most fine-grained approach, which is the fiddliest to use but puts the caller in the most control.

Time Machine has one built-in source of time zone data available: a copy of the tz database (also known as the IANA Time Zone database, or zoneinfo or Olson database).

To obtain a DateTimeZone for a given timezone ID, use one of the methods on DateTimeZoneProvider (and see DateTimeZoneProviders for access to the built-in providers). The UTC timezone is also available via the utc property on this class.

To obtain a DateTimeZone representing the system default time zone, you can either call DateTimeZoneProvider.getSystemDefault on a provider to obtain the DateTimeZone that the provider considers matches the system default time zone

Note that Time Machine does not require that DateTimeZone instances be singletons. Comparing two time zones for equality is not straightforward: if you care about whether two zones act the same way within a particular portion of time, use ZoneEqualityComparer. Additional guarantees are provided by DateTimeZoneProvider and DateTimeZone.forOffset.

Annotations

@immutable

Constructors

DateTimeZone(String id, bool isFixed, Offset minOffset, Offset maxOffset): Initializes a new instance of the DateTimeZone class.
DateTimeZone.forOffset(Offset offset): Returns a fixed time zone with the given offset.
factory

Properties

hashCode → int: The hash code for this object.
no setterinherited
id → String: Get the provider's ID for the time zone.
final
maxOffset → Offset: Gets the greatest (most positive) offset within this time zone, over all time.
final
minOffset → Offset: Gets the least (most negative) offset within this time zone, over all time.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

getUtcOffset(Instant instant) → Offset: Returns the offset from UTC, where a positive duration indicates that local time is later than UTC. In other words, local time = UTC + offset.
getZoneInterval(Instant instant) → ZoneInterval: Gets the zone interval for the given instant; the range of time around the instant in which the same Offset applies (with the same split between standard time and daylight saving time, and with the same offset).
getZoneIntervals(Interval interval) → Iterable<ZoneInterval>: Returns all the zone intervals which occur for any instant in the given interval.
getZoneIntervalsFromTo(Instant start, Instant end) → Iterable<ZoneInterval>: Returns all the zone intervals which occur for any instant in the interval [start, end).
getZoneIntervalsOptions(Interval interval, ZoneEqualityComparerOptions options) → Iterable<ZoneInterval>: Returns the zone intervals within the given interval, potentially coalescing some of the original intervals according to options.
mapLocal(LocalDateTime localDateTime) → ZoneLocalMapping: Returns complete information about how the given LocalDateTime is mapped in this time zone.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: Returns the ID of this time zone.
override

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

local → DateTimeZone: Gets the local DateTimeZone of the local machine if the DateTimeZoneProviders.defaultProvider is defined, or utc.
no setter
utc → DateTimeZone: Gets the UTC (Coordinated Universal Time) time zone.
final