Class DateTimeZoneCache

Provides an implementation of IDateTimeZoneProvider that caches results from an IDateTimeZoneSource.
Since 1.0.x
Availability net35-Client, PCL
Inheritance
Object
DateTimeZoneCache
Implements
Inherited Members
Object.ToString()
Object.Equals(Object)
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetHashCode()
Object.GetType()
Object.MemberwiseClone()
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 net35-Client, PCL
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
System.ArgumentNullException source is null.
InvalidDateTimeZoneSourceException source violates its contract.

Properties

Ids

Gets the list of valid time zone ids advertised by this provider.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ReadOnlyCollection<string> Ids { get; }
Property Value
Type Description
ReadOnlyCollection<String> The System.Collections.Generic.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.
Since 1.0.x
Availability net35-Client, PCL
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. 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.
System.ArgumentNullException id is null.

VersionId

The version ID of this provider. This is simply the VersionId returned by the underlying source.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public string VersionId { get; }
Property Value
Type Description
String

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 net35-Client, PCL
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 System.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.
Since 1.0.x
Availability net35-Client, PCL
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. These must return instances that are equal to those returned by ForOffset(Offset).

Exceptions
Type Condition
System.ArgumentNullException id is null.

Implements

See Also