Early Preview

This is currently very much a preview. Please feel free to try things out, but don't be upset if anything is not yet working. Feedback is welcome over on our GitHub Dicussions page.

interface NodaTime.​IDateTimeZoneProvider

Assembly: NodaTime

Provides stable, performant time zone data.

Remarks

<para>Consumers should be able to treat an <see cref="T:NodaTime.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.</para> <para>Implementations designed to work with any <see cref="T:NodaTime.TimeZones.IDateTimeZoneSource" /> implementation (such as <see cref="T:NodaTime.TimeZones.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.</para>

Properties

string
VersionId
Gets the version ID of this provider.
Ids
Gets the list of valid time zone ids advertised by this provider.
Remarks <para> 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. </para> <para> 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. </para>
Item

Methods

GetSystemDefault​()
Gets the time zone from this provider that matches the system default time zone, if a matching time zone is available.
Returns The provider-specific representation of the system default time zone.
Remarks <para> Callers should be aware that this method will throw <see cref="T:NodaTime.TimeZones.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. </para> <para> If it is necessary to handle this case, callers can construct a <see cref="T:NodaTime.TimeZones.BclDateTimeZone" /> via <see cref="M:NodaTime.TimeZones.BclDateTimeZone.ForSystemDefault" />, which returns a <see cref="T:NodaTime.DateTimeZone" /> that wraps the system local <see cref="T:System.TimeZoneInfo" />, and which always succeeds. Note that <c>BclDateTimeZone</c> may not be available in all versions of Noda Time 1.x and 2.x; see the class documentation for more details. </para>
GetZoneOrNull​(string id)
Returns the time zone for the given ID, if it's available.
Returns The <see cref="T:NodaTime.DateTimeZone" /> for the given ID or null if the provider does not support the given ID.
id The time zone ID to find.
Remarks <para> Note that this may return a <see cref="T:NodaTime.DateTimeZone" /> that has a different ID to that requested, if the ID provided is an alias. </para> <para> Note also that this method is not required to return the same <see cref="T:NodaTime.DateTimeZone" /> instance for successive requests for the same ID; however, all instances returned for a given ID must compare as equal. </para> <para> The fixed-offset timezones with IDs "UTC" and "UTC+/-Offset" are always available. </para>