Class TzdbDateTimeZoneSource

Provides an implementation of IDateTimeZoneSource that loads data originating from the tz database (also known as the IANA Time Zone database, or zoneinfo or Olson database).
Inheritance
object
TzdbDateTimeZoneSource
Implements
Inherited Members
Namespace: NodaTime.TimeZones
Assembly: NodaTime.dll
Syntax
public sealed class TzdbDateTimeZoneSource : IDateTimeZoneSource
Remarks
All calls to ForId(string) for fixed-offset IDs advertised by the source (i.e. "UTC" and "UTC+/-Offset") will return zones equal to those returned by ForOffset(Offset).

Properties

Aliases

Gets a lookup from canonical time zone ID (e.g. "Europe/London") to a group of aliases for that time zone (e.g. {"Europe/Belfast", "Europe/Guernsey", "Europe/Jersey", "Europe/Isle_of_Man", "GB", "GB-Eire"}).
Declaration
public ILookup<string, string> Aliases { get; }
Property Value
Type Description
ILookup<string, string> A lookup from canonical ID to the aliases of that ID.
Remarks
The group of values for a key never contains the canonical ID, only aliases. Any time zone ID which is itself an alias or has no aliases linking to it will not be present in the lookup. The aliases within a group are returned in alphabetical (ordinal) order.

CanonicalIdMap

Returns a read-only map from time zone ID to the canonical ID. For example, the key "Europe/Jersey" would be associated with the value "Europe/London".
Declaration
public IDictionary<string, string> CanonicalIdMap { get; }
Property Value
Type Description
IDictionary<string, string> A map from time zone ID to the canonical ID.
Remarks

This map contains an entry for every ID returned by GetIds(), where canonical IDs map to themselves.

The returned map is read-only; any attempts to call a mutating method will throw NotSupportedException.

Default

Gets the TzdbDateTimeZoneSource initialised from resources within the NodaTime assembly.
Declaration
public static TzdbDateTimeZoneSource Default { get; }
Property Value
Type Description
TzdbDateTimeZoneSource The source initialised from resources within the NodaTime assembly.
Remarks
All calls to ForId(string) for fixed-offset IDs advertised by the source (i.e. "UTC" and "UTC+/-Offset") will return zones equal to those returned by ForOffset(Offset).

TzdbToWindowsIds

Returns a dictionary mapping TZDB IDs to Windows IDs.
Declaration
public IReadOnlyDictionary<string, string> TzdbToWindowsIds { get; }
Property Value
Type Description
IReadOnlyDictionary<string, string>
Remarks

Where a TZDB alias isn't present directly in the Windows mapping, but its canonical ID is, the dictionary will contain an entry for the alias as well. For example, the TZDB ID "Africa/Asmara" is an alias for "Africa/Nairobi", which has a Windows ID of "E. Africa Standard Time". "Africa/Asmara" doesn't appear in the Windows mapping directly, but it will still be present in the returned dictionary.

Where a TZDB canonical ID isn't present in the Windows mapping, but an alias is, the dictionary will contain an entry for the canonical ID as well. For example, the Windows mapping uses the TZDB ID "Asia/Calcutta" for "India Standard Time". This is an alias for "Asia/Kolkata" in TZDB, so the returned dictionary will have an entry mapping "Asia/Kolkata" to "Asia/Calcutta". If multiple aliases for the same canonical ID have entries in the Windows mapping with different Windows IDs, the alias that is earliest in lexicographical ordering determines the value for the entry.

If a canonical ID is not present in the mapping, nor any of its aliases, it will not be present in the returned dictionary.

TzdbVersion

Gets just the TZDB version (e.g. "2013a") of the source data.
Declaration
public string TzdbVersion { get; }
Property Value
Type Description
string The TZDB version (e.g. "2013a") of the source data.
Remarks
All calls to ForId(string) for fixed-offset IDs advertised by the source (i.e. "UTC" and "UTC+/-Offset") will return zones equal to those returned by ForOffset(Offset).

VersionId

Returns an appropriate version ID for diagnostic purposes, which must not be null.
Declaration
public string VersionId { get; }
Property Value
Type Description
string An appropriate version ID for diagnostic purposes.
Remarks

This source returns a string such as "TZDB: 2013b (mapping: 8274)" corresponding to the versions of the tz database and the CLDR Windows zones mapping file.

Note that there is no need to parse this string to extract any of the above information, as it is available directly from the TzdbVersion and Version properties.

WindowsMapping

Gets the Windows time zone mapping information provided in the CLDR supplemental "windowsZones.xml" file.
Declaration
public WindowsZones WindowsMapping { get; }
Property Value
Type Description
WindowsZones The Windows time zone mapping information provided in the CLDR supplemental "windowsZones.xml" file.
Remarks
All calls to ForId(string) for fixed-offset IDs advertised by the source (i.e. "UTC" and "UTC+/-Offset") will return zones equal to those returned by ForOffset(Offset).

WindowsToTzdbIds

Returns a dictionary mapping Windows IDs to canonical TZDB IDs, using the primary mapping in each MapZone.
Declaration
public IReadOnlyDictionary<string, string> WindowsToTzdbIds { get; }
Property Value
Type Description
IReadOnlyDictionary<string, string>
Remarks
Sometimes the Windows mapping contains values which are not canonical TZDB IDs. Every value in the returned dictionary is a canonical ID. For example, the Windows mapping contains as "Asia/Calcutta" for the Windows ID "India Standard Time", but "Asia/Calcutta" is an alias for "Asia/Kolkata". The entry for "India Standard Time" in the returned dictionary therefore has "Asia/Kolkata" as the value.

Zone1970Locations

Gets a read-only list of "zone 1970" locations known to this source, or null if the original source data does not include zone locations.
Declaration
public IList<TzdbZone1970Location>? Zone1970Locations { get; }
Property Value
Type Description
IList<TzdbZone1970Location> A read-only list of zone locations known to this source.
Remarks

This location data differs from ZoneLocations in two important respects:

  • Where multiple similar zones exist but only differ in transitions before 1970, this location data chooses one zone to be the canonical "post 1970" zone.
  • This location data can represent multiple ISO-3166 country codes in a single entry. For example, the entry corresponding to "Europe/London" includes country codes GB, GG, JE and IM (Britain, Guernsey, Jersey and the Isle of Man, respectively).

Every zone location's time zone ID is guaranteed to be valid within this source (assuming the source has been validated).

ZoneLocations

Gets a read-only list of zone locations known to this source, or null if the original source data does not include zone locations.
Declaration
public IList<TzdbZoneLocation>? ZoneLocations { get; }
Property Value
Type Description
IList<TzdbZoneLocation> A read-only list of zone locations known to this source.
Remarks
Every zone location's time zone ID is guaranteed to be valid within this source (assuming the source has been validated).

Methods

ForId(string)

Returns the time zone definition associated with the given ID.
Declaration
public DateTimeZone ForId(string id)
Parameters
Type Name Description
string id The ID of the time zone to return. This must be one of the IDs returned by GetIds().
Returns
Type Description
DateTimeZone The DateTimeZone for the given ID.
Remarks

Note that this is permitted to return a DateTimeZone that has a different ID to that requested, if the ID provided is an alias.

Note also that this method is not required to return the same DateTimeZone instance for successive requests for the same ID; however, all instances returned for a given ID must compare as equal.

It is advised that sources should document their behaviour regarding any fixed-offset timezones (i.e. "UTC" and "UTC+/-Offset") that are included in the list returned by GetIds(). (These IDs will not be requested by DateTimeZoneCache, but any users calling into the source directly may care.)

The source need not attempt to cache time zones; caching is typically provided by DateTimeZoneCache.

Exceptions
Type Condition
ArgumentException id is not supported by this source.

FromStream(Stream)

Creates an instance from a stream in the custom Noda Time format. The stream must be readable.
Declaration
public static TzdbDateTimeZoneSource FromStream(Stream stream)
Parameters
Type Name Description
Stream stream The stream containing time zone data
Returns
Type Description
TzdbDateTimeZoneSource A TzdbDateTimeZoneSource providing information from the given stream.
Remarks

The stream is not closed by this method, but will be read from without rewinding. A successful call will read the stream to the end.

See the user guide for instructions on how to generate an updated time zone database file from a copy of the (textual) tz database.

Exceptions
Type Condition
InvalidNodaDataException The stream contains invalid time zone data, or data which cannot be read by this version of Noda Time.
IOException Reading from the stream failed.
InvalidOperationException The supplied stream doesn't support reading.

GetIds()

Returns an unordered enumeration of the IDs available from this source.
Declaration
public IEnumerable<string> GetIds()
Returns
Type Description
IEnumerable<string> The IDs available from this source.
Remarks

Every value in this enumeration must return a valid time zone from ForId(string) for the life of the source. The enumeration may be empty, but must not be null, and must not contain any elements which are null. It should not contain duplicates: this is not enforced, and while it may not have a significant impact on clients in some cases, it is generally unfriendly. The built-in implementations never return duplicates.

The source is not required to provide the IDs in any particular order, although they should be distinct.

Note that this list may optionally contain any of the fixed-offset timezones (with IDs "UTC" and "UTC+/-Offset"), but there is no requirement they be included.

GetSystemDefaultId()

Returns this source's ID for the system default time zone.
Declaration
public string? GetSystemDefaultId()
Returns
Type Description
string The ID for the system default time zone for this source, or null if the system default time zone has no mapping in this source.
Remarks
All calls to ForId(string) for fixed-offset IDs advertised by the source (i.e. "UTC" and "UTC+/-Offset") will return zones equal to those returned by ForOffset(Offset).

Validate()

Validates that the data within this source is consistent with itself.
Declaration
public void Validate()
Remarks
Source data is not validated automatically when it's loaded, but any source loaded from data produced by NodaTime.TzdbCompiler (including the data shipped with Noda Time) will already have been validated via this method when it was originally produced. This method should only normally be called explicitly if you have data from a source you're unsure of.
Exceptions
Type Condition
InvalidNodaDataException The source data is invalid. The source may not function correctly.

Implements