Interface IDateTimeZoneProvider

Provides stable, performant time zone data.

Namespace: NodaTime

Assembly: NodaTime.dll

Syntax

public interface IDateTimeZoneProvider

Remarks

Consumers should be able to treat an IDateTimeZoneProvider like a cache: lookups should be quick (after at most one lookup of a given ID), and the data for a given ID should always be the same (even if the specific instance returned is not). Consumers should not feel the need to cache data accessed through this interface.

Implementations designed to work with any IDateTimeZoneSource implementation (such as DateTimeZoneCache) should not attempt to handle exceptions thrown by the source. A source-specific provider may do so, as it has more detailed knowledge of what can go wrong and how it can best be handled.

Properties

Ids

Gets the list of valid time zone ids advertised by this provider.

Declaration

ReadOnlyCollection<string> Ids { get; }

Property Value

Type	Description
ReadOnlyCollection<String>	The IEnumerable<T> of string ids.

Remarks

This list will be sorted in ordinal lexicographic order. It cannot be modified by callers, and must not be modified by the provider either: client code can safely treat it as thread-safe and deeply immutable.

In addition to the list returned here, providers always support the fixed-offset timezones with IDs "UTC" and "UTC+/-Offset". These may or may not be included explicitly in this list.

Item[String]

Returns the time zone for the given ID.

Declaration

DateTimeZone this[string id] { get; }

Parameters

Type	Name	Description
String	id	The time zone id to find.

Property Value

Type	Description
DateTimeZone	The DateTimeZone for the given ID.

Remarks

Unlike GetZoneOrNull(String), this indexer will never return a null reference. If the ID is not supported by this provider, it will throw DateTimeZoneNotFoundException.

Note that this may 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.

The fixed-offset timezones with IDs "UTC" and "UTC+/-Offset" are always available. These must return instances that are equal to those returned by ForOffset(Offset).

Exceptions

Type	Condition
DateTimeZoneNotFoundException	This provider does not support the given ID.
ArgumentNullException	id is null.

VersionId

The version ID of this provider.

Declaration

string VersionId { get; }

Property Value

Type	Description
String

Remarks

Consumers should be able to treat an IDateTimeZoneProvider like a cache: lookups should be quick (after at most one lookup of a given ID), and the data for a given ID should always be the same (even if the specific instance returned is not). Consumers should not feel the need to cache data accessed through this interface.

Implementations designed to work with any IDateTimeZoneSource implementation (such as DateTimeZoneCache) should not attempt to handle exceptions thrown by the source. A source-specific provider may do so, as it has more detailed knowledge of what can go wrong and how it can best be handled.

Methods

GetSystemDefault()

Gets the time zone from this provider that matches the system default time zone, if a matching time zone is available.

Declaration

DateTimeZone GetSystemDefault()

Returns

Type	Description
DateTimeZone	The provider-specific representation of the system default time zone.

Remarks

Callers should be aware that this method will throw DateTimeZoneNotFoundException if no matching time zone is found. For the built-in Noda Time providers, this is unlikely to occur in practice (assuming the system is using a standard Windows time zone), but can occur even then, if no mapping is found. The TZDB source contains mappings for almost all Windows system time zones, but a few (such as "Mid-Atlantic Standard Time") are unmappable.

If it is necessary to handle this case, callers can construct a BclDateTimeZone via ForSystemDefault(), which returns a DateTimeZone that wraps the system local TimeZoneInfo, and which always succeeds. Note that BclDateTimeZone is not available on the PCL build of Noda Time, so this fallback strategy can only be used with the desktop version.

Exceptions

Type	Condition
DateTimeZoneNotFoundException	The system default time zone is not mapped by this provider.

GetZoneOrNull(String)

Returns the time zone for the given ID, if it's available.

Declaration

DateTimeZone GetZoneOrNull(string id)

Parameters

Type	Name	Description
String	id	The time zone ID to find.

Returns

Type	Description
DateTimeZone	The DateTimeZone for the given ID or null if the provider does not support the given ID.

Remarks

Note that this may 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.

The fixed-offset timezones with IDs "UTC" and "UTC+/-Offset" are always available. These must return instances that are equal to those returned by ForOffset(Offset).

Exceptions

Type	Condition
ArgumentNullException	id is null.