Interface IDateTimeZoneSource

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

Since 1.0.x

Availability net35-Client, PCL

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 typically provided by DateTimeZoneCache, which most consumers should use instead of consuming IDateTimeZoneSource directly in order to get better performance.

It is expected that any exceptions thrown are implementation-specific; nothing is explicitly specified in the interface. Typically this would be unusual to the point that callers would not try to catch them; any implementation which may break in ways that are sensible to catch should advertise this clearly, so that clients will know to handle the exceptions appropriately. No wrapper exception type is provided by Noda Time to handle this situation, and code in Noda Time does not try to catch such exceptions.

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. 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

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, PCL

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

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
System.ArgumentNullException	id is null.
ArgumentException	id is not supported by this source.

GetIds()

Returns an unordered enumeration of the IDs available from this source.

Since 1.0.x

Availability net35-Client, PCL

Declaration

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

string MapTimeZoneId(TimeZoneInfo timeZone)

Parameters

Type	Name	Description
TimeZoneInfo	timeZone	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.