Class DateTimeZoneCache

Provides an implementation of IDateTimeZoneProvider that caches results from an IDateTimeZoneSource.

Since 1.0.x

Availability net6.0, net8.0, netstandard2.0

Inheritance

object

DateTimeZoneCache

Implements

IDateTimeZoneProvider

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: NodaTime.TimeZones

Assembly: NodaTime.dll

Syntax

public sealed class DateTimeZoneCache : IDateTimeZoneProvider

Remarks

The process of loading or creating time zones may be an expensive operation. This class implements an unlimited-size non-expiring cache over a time zone source, and adapts an implementation of the IDateTimeZoneSource interface to an IDateTimeZoneProvider.

Constructors

DateTimeZoneCache(IDateTimeZoneSource)

Creates a provider backed by the given IDateTimeZoneSource.

Since 1.0.x

Availability net6.0, net8.0, netstandard2.0

Declaration

public DateTimeZoneCache(IDateTimeZoneSource source)

Parameters

Type	Name	Description
IDateTimeZoneSource	source	The IDateTimeZoneSource for this provider.

Remarks

Note that the source will never be consulted for requests for the fixed-offset timezones "UTC" and "UTC+/-Offset" (a standard implementation will be returned instead). This is true even if these IDs are advertised by the source.

Exceptions

Type	Condition
InvalidDateTimeZoneSourceException	source violates its contract.

Properties

Ids

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

Since 1.0.x

Availability net6.0, net8.0, netstandard2.0

Declaration

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

this[string]

Returns the time zone for the given ID.

Since 1.0.x

Availability net6.0, net8.0, netstandard2.0

Declaration

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

Exceptions

Type	Condition
DateTimeZoneNotFoundException	This provider does not support the given ID.

VersionId

Gets the version ID of this provider. This is simply the VersionId returned by the underlying source.

Since 1.0.x

Availability net6.0, net8.0, netstandard2.0

Declaration

public string VersionId { get; }

Property Value

Type	Description
string	The version ID of this provider.

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 net6.0, net8.0, netstandard2.0

Declaration

public 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 may not be available in all versions of Noda Time 1.x and 2.x; see the class documentation for more details.

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 net6.0, net8.0, netstandard2.0

Declaration

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

Implements

IDateTimeZoneProvider

Extension Methods

DateTimeZoneProviderExtensions.GetAllZones(IDateTimeZoneProvider)

See Also

DateTimeZoneProviders