Timezone class abstract

A timezone that contains rules defining how an offset varies for a single timezone.

There are two types of Timezones:

  • Those that have a fixed offset at all points in time.
  • Those that have offsets which vary across points in time, typically due to daylight savings time.

By default, most timezones in the 2023c TZ database are supported. This can be configured by replacing timezoneProvider. Similarly, retrieval of the platform's timezone can be configured by replacing platformTimezoneProvider.

Caveats

By default, Timezone.now without specifying a timezone only works on Windows, MacOS, Linux and web. The Factory timezone will be returned on all other platforms. This is due to limitations with dart:ffi. See Timezone.platformTimezoneProvider.

Timezones Transitions

Obtaining the offset for a local date-time is not trivial. Due to timezone transitions, it is possible for a local date-time to be ambiguous or invalid. There are three cases.

Normal, with one valid offset. This is the case for most of the year.

Gap, with zero offsets. This is when the clock jumps forward, when transitioning from winter to summer time. If a local date-time fails in the middle of a gap, the offset after the gap, i.e. summer time, is returned.

Clock jumping forward

Overlap, with two valid offsets. This is when clocks are set back, typically when transitioning from summer to winter time. If a local date-time falls in the middle of an overlap, the offset before the overlap, i.e. winter time, is returned.

Clock moving backwards

Constructors

Timezone(String name)
Creates a Timezone from the name, typically a TZ database timezone identifier such as Asia/Singapore, or factory if the name could not be parsed.
factory
Timezone.from(String name)
Creates a Timezone.
const
Timezone.now()
Creates a Timezone with the current timezone, or factory if the current timezone could not be retrieved.
factory

Properties

hashCode → int
The hash code for this object.
no setterinherited
name → String
The timezone name, typically a TZ database timezone identifier such as Asia/Singapore.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

convert({required int local}) → (EpochMicroseconds, TimezoneSpan)
Converts the local date-time in microseconds to microseconds since Unix epoch (in UTC). The corresponding TimezoneSpan is also returned.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
span({required EpochMicroseconds at}) → TimezoneSpan
Returns the TimezoneSpan at the microseconds since Unix epoch.
toString() → String
A string representation of this object.
override

Operators

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

Static Properties

factory → Timezone
The Factory timezone in the TZ database that has no offset.
no setter
platformTimezoneProvider ↔ String Function()
A callback that retrieves the platform's timezone.
getter/setter pair
timezoneProvider ↔ Map<String, Timezone>
All known TZ database timezone identifiers associated with the timezones.
getter/setter pair