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).
Since 1.0.x
Availability net45, netstandard1.3
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"}).
Since 1.1.x
Availability net45, netstandard1.3
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".
Since 1.1.x
Availability net45, netstandard1.3
Declaration
public IDictionary<string, string> CanonicalIdMap { get; }
Property Value
Type Description
IDictionary<String, String> A map from time zone ID to the canonical ID. (The value returned is never null.)
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.
Since 1.1.x
Availability net45, netstandard1.3
Declaration
public static TzdbDateTimeZoneSource Default { get; }
Property Value
Type Description
TzdbDateTimeZoneSource The source initialised from resources within the NodaTime assembly.

TzdbVersion

Gets just the TZDB version (e.g. "2013a") of the source data.
Since 1.1.x
Availability net45, netstandard1.3
Declaration
public string TzdbVersion { get; }
Property Value
Type Description
String The TZDB version (e.g. "2013a") of the source data. (The value returned is never null.)

VersionId

Returns an appropriate version ID for diagnostic purposes, which must not be null.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public string VersionId { get; }
Property Value
Type Description
String An appropriate version ID for diagnostic purposes, which must not be null.
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.
Since 1.1.x
Availability net45, netstandard1.3
Declaration
public WindowsZones WindowsMapping { get; }
Property Value
Type Description
WindowsZones The Windows time zone mapping information provided in the CLDR supplemental "windowsZones.xml" file. (The value returned is never null.)

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.
Since 2.0.x
Availability net45, netstandard1.3
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.
Since 1.1.x
Availability net45, netstandard1.3
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.
Since 1.0.x
Availability net45, netstandard1.3
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.
ArgumentNullException id is null.

FromStream(Stream)

Creates an instance from a stream in the custom Noda Time format. The stream must be readable.
Since 1.1.x
Availability net45, netstandard1.3
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.
ArgumentNullException stream is null.

GetIds()

Returns an unordered enumeration of the IDs available from this source.
Since 1.0.x
Availability net45, netstandard1.3
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.
Since 2.0.x
Availability net45, netstandard1.3
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.

Validate()

Validates that the data within this source is consistent with itself.
Since 1.1.x
Availability net45, netstandard1.3
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