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 net35-Client, PCL
Inheritance
Object
TzdbDateTimeZoneSource
Implements
Inherited Members
Object.ToString()
Object.Equals(Object)
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetHashCode()
Object.GetType()
Object.MemberwiseClone()
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).

Constructors

TzdbDateTimeZoneSource(ResourceManager)

Initializes a new instance of the TzdbDateTimeZoneSource class.
Since 1.0.x
Availability net35-Client
Declaration
[Obsolete("The resource format for time zone data is deprecated; future versions will only support blob-based data")]
public TzdbDateTimeZoneSource(ResourceManager manager)
Parameters
Type Name Description
ResourceManager manager The System.Resources.ResourceManager to search for the time zone resources.
Exceptions
Type Condition
InvalidNodaDataException The data within the resource manager is invalid.

TzdbDateTimeZoneSource(ResourceSet)

Initializes a new instance of the TzdbDateTimeZoneSource class.
Since 1.0.x
Availability net35-Client
Declaration
[Obsolete("The resource format for time zone data is deprecated; future versions will only support blob-based data")]
public TzdbDateTimeZoneSource(ResourceSet source)
Parameters
Type Name Description
ResourceSet source The System.Resources.ResourceSet to search for the time zone resources.
Exceptions
Type Condition
InvalidNodaDataException The data within the resource set is invalid.

TzdbDateTimeZoneSource(String)

Initializes a new instance of the TzdbDateTimeZoneSource class from a resource within the NodaTime assembly.
Since 1.0.x
Availability net35-Client
Declaration
[Obsolete("Use TzdbDateTimeZoneSource.Default to access the only TZDB resources within the NodaTime assembly")]
public TzdbDateTimeZoneSource(string baseName)
Parameters
Type Name Description
String baseName The root name of the resource file.
Remarks
For backwards compatibility, this will use the blob time zone data when given the same base name which would previously have loaded the now-obsolete resource data.
Exceptions
Type Condition
InvalidNodaDataException The data within the resource is invalid.
System.Resources.MissingManifestResourceException The resource set cannot be found.

TzdbDateTimeZoneSource(String, Assembly)

Initializes a new instance of the TzdbDateTimeZoneSource class.
Since 1.0.x
Availability net35-Client
Declaration
[Obsolete("The resource format for time zone data is deprecated; future versions will only support blob-based data")]
public TzdbDateTimeZoneSource(string baseName, Assembly assembly)
Parameters
Type Name Description
String baseName The root name of the resource file.
Assembly assembly The assembly to search for the time zone resources.
Remarks
For backwards compatibility, this will use the blob time zone data when given the same base name which would previously have loaded the now-obsolete resource data from the Noda Time assembly itself.
Exceptions
Type Condition
InvalidNodaDataException The data within the resource is invalid.
System.Resources.MissingManifestResourceException The resource set cannot be found.

Properties

Aliases

Returns 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 net35-Client, PCL
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 net35-Client, PCL
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 System.NotSupportedException.

Default

The TzdbDateTimeZoneSource initialised from resources within the NodaTime assembly.
Since 1.1.x
Availability net35-Client, PCL
Declaration
public static TzdbDateTimeZoneSource Default { get; }
Property Value
Type Description
TzdbDateTimeZoneSource

TzdbVersion

Returns just the TZDB version (e.g. "2013a") of the source data.
Since 1.1.x
Availability net35-Client, PCL
Declaration
public string TzdbVersion { get; }
Property Value
Type Description
String

VersionId

Returns an appropriate version ID for diagnostic purposes, which must not be null. This doesn't have any specific format; it's solely for diagnostic purposes. The included sources return strings of the format "source identifier: source version" indicating where the information comes from and which version of the source information has been loaded.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public string VersionId { get; }
Property Value
Type Description
String
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 net35-Client, PCL
Declaration
public WindowsZones WindowsMapping { get; }
Property Value
Type Description
WindowsZones

ZoneLocations

Returns a read-only list of zone locations known to this source.
Since 1.1.x
Availability net35-Client, PCL
Declaration
public IList<TzdbZoneLocation> ZoneLocations { get; }
Property Value
Type Description
IList<TzdbZoneLocation>
Remarks

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

The legacy resource format does not include location information, and this property will throw an exception if the information is requested. It is expected that callers who wish to use newer features will not be attempting to use legacy formats for time zone data.

Exceptions
Type Condition
System.InvalidOperationException This is a legacy resource-based data source which does not include location information.

Methods

ForId(String)

Returns the time zone definition associated with the given ID.
Since 1.0.x
Availability net35-Client, PCL
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.
Since 1.1.x
Availability net35-Client, PCL
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.
System.IO.IOException Reading from the stream failed.
System.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 net35-Client, PCL
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.

MapTimeZoneId(TimeZoneInfo)

Returns this source's corresponding ID for the given BCL time zone.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public string MapTimeZoneId(TimeZoneInfo zone)
Parameters
Type Name Description
TimeZoneInfo zone The BCL time zone, which must be a known system time zone.
Returns
Type Description
String The ID for the given system time zone for this source, or null if the system 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 net35-Client, PCL
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