TzDataTimezone Struct

Definition

Namespace: DataStandardizer.Chronology

A TZ Database time zone. You don’t construct these; instead use the predefined static instances, grouped by region and named after the database’s hierarchical identifiers — for example TzDataTimezone.Europe.Berlin and TzDataTimezone.America.Argentina.Buenos_Aires.

public readonly struct TzDataTimezone : IComparable, IEquatable<TzDataTimezone>, IParsable<TzDataTimezone>

IParsable<TzDataTimezone> is implemented on net10.0 only.

Remarks

To get a time zone from its identifier string, use Parse, TryParse or the explicit cast from string. They return the predefined instance with that identifier, and reject identifiers that are not those of a predefined instance. Identifiers are case-sensitive. They also accept the deprecated names in the TZ Database’s backward file, and return the canonical time zone each refers to: Parse("Asia/Calcutta") and (TzDataTimezone)"Asia/Calcutta" both return TzDataTimezone.Asia.Kolkata.

Per-zone location metadata (latitude, longitude, ISO country codes, comment) is read through the Latitude, Longitude, IsoCountryCodes and Comment properties. See Access time zone metadata.

Each time zone carries its full history from the TZ Database, read through the ZoneLines property as a list of TzDataZoneLine. The extension methods on TzDataExtensions use it to calculate the offset from universal time, daylight saving time, transitions and abbreviations at any instant. See Calculate UTC offsets.

Cast and default instances

The explicit cast from a string returns the predefined instance with that identifier, so it carries the same zone lines and metadata:

var london = (TzDataTimezone)"Europe/London";
bool same = london == TzDataTimezone.Europe.London;   // true

The cast throws InvalidCastException for a string that is not the identifier of a predefined instance or a deprecated name, and for null. Use TryParse when the string may not be an identifier.

The default instance

default(TzDataTimezone) is a valid time zone: Coordinated Universal Time, Etc/UTC, in the same way that default(TimeSpan) is TimeSpan.Zero. It is equal to TzDataTimezone.Etc.UTC, with the same hash code, and every member treats it as that time zone:

var timezone = default(TzDataTimezone);
bool same = timezone == TzDataTimezone.Etc.UTC;                   // true
string identifier = timezone;                                     // "Etc/UTC"
TimeSpan offset = timezone.GetUtcOffset(DateTime.UtcNow);         // TimeSpan.Zero
string abbreviation = timezone.GetAbbreviation(DateTime.UtcNow);  // "UTC"

Etc/UTC is defined in the TZ Database’s etcetera file, with an offset of 0, the abbreviation UTC and no daylight saving time, so it has no transitions. It is used in no country and has no location, so IsoCountryCodes is empty, Comment is null, and Latitude and Longitude are 0. It is not a link, so IsLink is false and Canonical is the time zone itself.

TryParse sets result to default when it returns false, so check its return value rather than result to tell whether the string was an identifier.

The canonical time zones are those listed in the TZ Database’s zone1970.tab, each with its own history. Some time zones listed in zone.tab are instead links to a canonical time zone, because their clocks have agreed with it since 1970: Europe/Oslo and Europe/Stockholm are links to Europe/Berlin, for example. Each such link has its own field, such as TzDataTimezone.Europe.Oslo, with its own location metadata from zone.tab, but shares the zone lines of its canonical time zone. Where a link refers to another link, it is resolved to the canonical time zone at the end of the chain.

A link’s history before 1970 is that of its canonical time zone, not the local history of the place it names: TzDataTimezone.Europe.Oslo.ZoneLines shows Berlin’s history, including the offsets Berlin observed before 1970.

IsLink tells you whether a time zone is a link, and Canonical returns the canonical time zone it links to, or the time zone itself if it is canonical. Equality is based on the identifier, so Europe.Oslo != Europe.Berlin, and a link’s identifier is kept unchanged. To ask whether two time zones share their history, compare their Canonical time zones:

var oslo = TzDataTimezone.Europe.Oslo;
bool same = oslo == TzDataTimezone.Europe.Berlin;                     // false
bool shared = oslo.Canonical == TzDataTimezone.Europe.Berlin.Canonical; // true

The deprecated names in the TZ Database’s backward file, such as Asia/Calcutta and US/Eastern, have no fields. Parse and TryParse return the canonical time zone for them. The names that backward links to Etc/UTC, such as UTC and Zulu, return TzDataTimezone.Etc.UTC. GMT, which etcetera links to Etc/GMT, and the names that backward links to it, such as Greenwich and GMT0, return TzDataTimezone.Etc.GMT.

The time zones are those listed in zone1970.tab and zone.tab, with Etc/UTC and Etc/GMT from etcetera. The other zones of etcetera, Etc/GMT-14 to Etc/GMT+12, which have fixed offsets and are used in no country, aren’t included, so Parse and TryParse reject their identifiers.

Generated source

TzDataTimezone is a partial struct. Most of it is generated from the TZ Database source (tzdata) by scripts/GenerateTzDataTimezoneOfficial.ps1, which produces four source files:

File Contents
TzDataTimezone.cs The struct, its identifier members, and a field for each time zone, nested by region, with Etc.UTC and Etc.GMT from the etcetera file.
TzDataTimezone.ZoneLineData.cs The zone lines of each canonical time zone, which the fields of the time zone and of its links share.
TzDataTimezone.RuleSets.cs The daylight saving rule sets referenced by the zone lines.
TzDataTimezone.LinkData.cs The deprecated names from the backward file, and GMT from the etcetera file, which Parse and TryParse accept.

The zone line data, rule sets and link data are private. They are reached through ZoneLines and the methods of TzDataExtensions. The properties and parsing methods are hand-written, in TzDataTimezone.Members.cs, as is the identifier that the generated members use, which for the default instance is read from the Etc.UTC field.

The generated files need no manual edits. The script’s comment-based help (Get-Help ./scripts/GenerateTzDataTimezoneOfficial.ps1 -Full) lists the tzdata files it requires: zone1970.tab, zone.tab, iso3166.tab, the main-format region files (africa, antarctica, asia, australasia, europe, northamerica and southamerica), etcetera and backward. The TZ Database release a build is based on is given in the remarks on the type. See Data currency and versioning.

Fields

The time zone instances are grouped by region:

  • Africa — 19 time zones and 33 links
  • America — 121 time zones and 23 links
  • Antarctica — 8 time zones and 3 links
  • Arctic — 1 link
  • Asia — 74 time zones and 8 links
  • Atlantic — 8 time zones and 2 links
  • Australia — 11 time zones
  • Etc — 2 time zones, Etc/UTC, which the default instance stands for, and Etc/GMT
  • Europe — 38 time zones and 20 links
  • Indian — 3 time zones and 8 links
  • Pacific — 30 time zones and 8 links

Properties

Property Signature Notes
Canonical TzDataTimezone Canonical { get; } The canonical time zone that a link refers to, or this time zone if it is canonical.
Comment string? Comment { get; } The zone’s comment from zone1970.tab (zone.tab for a link), or null if it has none. Declared as string ([CanBeNull]) on the .NET Standard targets.
IsLink bool IsLink { get; } true if the time zone is a link to a canonical time zone; otherwise, false.
IsoCountryCodes IReadOnlyList<string> IsoCountryCodes { get; } ISO 3166-1 Alpha-2 codes for the countries the zone covers, in zone1970.tab order (zone.tab for a link). Empty for Etc/UTC.
Latitude double Latitude { get; } Latitude of the zone’s principal location, in decimal degrees. 0 for Etc/UTC, which has no location.
Longitude double Longitude { get; } Longitude of the zone’s principal location, in decimal degrees. 0 for Etc/UTC, which has no location.
ZoneLines IReadOnlyList<TzDataZoneLine> ZoneLines { get; } The zone’s full history of offsets from universal time, as TzDataZoneLine instances in chronological order. Every line but the last has an Until. For a link, those of its canonical time zone.

Methods

Static

Method Returns Notes
Parse(string s) TzDataTimezone Returns the predefined instance with identifier s, or the canonical instance for a deprecated name. Throws ArgumentNullException if s is null, and FormatException if it is not a known identifier.
Parse(string s, IFormatProvider? provider) TzDataTimezone IParsable<TzDataTimezone> implementation; net10.0 only. provider is ignored.
TryParse(string? s, out TzDataTimezone result) bool Returns false, with result set to default (Etc/UTC), if s is null or not a known identifier.
TryParse(string? s, IFormatProvider? provider, out TzDataTimezone result) bool IParsable<TzDataTimezone> implementation; net10.0 only. provider is ignored.

Implicit implementation

Method Returns Notes
CompareTo(object obj) int Compares the identifiers in ordinal order. Throws ArgumentNullException if obj is null, and ArgumentException if it is not a TzDataTimezone.
Equals(TzDataTimezone other) bool Compares the identifiers, so default equals Etc.UTC.
Equals(object obj) bool Override.
GetHashCode() int Override.
ToString() string Override. Returns the name of the time zone’s field in its region, such as Oslo for Europe.Oslo and UTC for Etc.UTC and default; for a field in a nested region, such as America.Argentina.Buenos_Aires, the identifier.
ToString(IFormatProvider provider) string  

Operators

Operator Signature Notes
Explicit explicit operator TzDataTimezone(string) Returns the predefined instance with the identifier, or the canonical instance for a deprecated name. Throws InvalidCastException for an unknown identifier or null.
Implicit implicit operator string(TzDataTimezone) Unwraps to the identifier string, which is "Etc/UTC" for default. Never returns null.
Equality operator ==, != (TzDataTimezone, TzDataTimezone)  

Applies to

Targets netstandard1.0, netstandard2.0, and net10.0.

See also


This site uses Just the Docs, a documentation theme for Jekyll.