Interface IDateTimeZoneProvider

Provides stable, performant time zone data.
Since 1.0.x
Availability net45, netstandard1.3
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 multiple calls for a given ID must always return references to equal instances, even if they are not references to a single instance. 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.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
ReadOnlyCollection<string> Ids { get; }
Property Value
Type Description
ReadOnlyCollection<String> The System.Collections.Generic.IEnumerable<T> of string ids. (The value returned is never null.)
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.
Since 1.0.x
Availability net45, netstandard1.3
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. (The value returned is never null.)
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.

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

VersionId

Gets the version ID of this provider.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
string VersionId { get; }
Property Value
Type Description
String The version ID of this provider. (The value returned is never null.)

Methods

GetSystemDefault()

Gets the time zone from this provider that matches the system default time zone, if a matching time zone is available.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
DateTimeZone GetSystemDefault()
Returns
Type Description
DateTimeZone The provider-specific representation of the system default time zone. (The value returned is never null.)
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 System.TimeZoneInfo, and which always succeeds. Note that BclDateTimeZone is not available on the .NET Standard 1.3 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.
Since 1.0.x
Availability net45, netstandard1.3
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.

Exceptions
Type Condition
ArgumentNullException id is null.

Extension Methods