Interface IDateTimeZoneSource

Provides the interface for objects that can retrieve time zone definitions given an ID.

Since 1.0.x

Availability net35-Client

Namespace: NodaTime.TimeZones

Assembly: NodaTime.dll

Syntax

public interface IDateTimeZoneSource

Remarks

The interface presumes that the available time zones are static; there is no mechanism for updating the list of available time zones. Any time zone ID that is returned in GetIds() must be resolved by ForId(String) for the life of the source.

Implementations need not cache time zones or the available time zone IDs. Caching is provided by DateTimeZoneCache, which most consumers should use instead of consuming IDateTimeZoneSource directly in order to get better performance.

Properties

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. For example, the default source returns a string such as "TZDB: 2011n" indicating where the information comes from and which version of that information it's loaded.

Since 1.0.x

Availability net35-Client

Declaration

string VersionId { get; }

Property Value

Type	Description
String

Methods

ForId(String)

Returns the time zone definition associated with the given id.

Since 1.0.x

Availability net35-Client

Declaration

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

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

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 anyway, but any users calling into the source directly may care.)

Exceptions

Type	Condition
System.ArgumentNullException	id is null.
ArgumentException	id is not supported by this source.

GetIds()

Returns an enumeration of the available ids from this source.

Since 1.0.x

Availability net35-Client

Declaration

IEnumerable<string> GetIds()

Returns

Type	Description
IEnumerable<String>	The System.Collections.Generic.IEnumerable<T> of ids. It may be empty, but must not be null, and must not contain any elements which are null.

Remarks

Every value in this enumeration must return a valid time zone from ForId(String) for the life of the source.

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

Declaration

string MapTimeZoneId(TimeZoneInfo timeZone)

Parameters

Type	Name	Description
TimeZoneInfo	timeZone

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.