Interface IDateTimeZoneSource
Namespace: NodaTime.TimeZones
Assembly: NodaTime.dll
Syntax
public interface IDateTimeZoneSourceRemarks
The interface presumes that the available time zones are static; there is no mechanism for updating the list of available time zones. Any time zone ID that is returned in GetIds() must be resolved by ForId(String) for the life of the source.
Implementations need not cache time zones or the available time zone IDs. Caching is typically provided by DateTimeZoneCache, which most consumers should use instead of consuming IDateTimeZoneSource directly in order to get better performance.
It is expected that any exceptions thrown are implementation-specific; nothing is explicitly specified in the interface. Typically this would be unusual to the point that callers would not try to catch them; any implementation which may break in ways that are sensible to catch should advertise this clearly, so that clients will know to handle the exceptions appropriately. No wrapper exception type is provided by Noda Time to handle this situation, and code in Noda Time does not try to catch such exceptions.
Properties
VersionId
Declaration
string VersionId { get; }Property Value
| Type | Description |
|---|---|
| String | An appropriate version ID for diagnostic purposes. (The value returned is never null.) |
Remarks
Methods
ForId(String)
Declaration
DateTimeZone ForId(string id)Parameters
| Type | Name | Description |
|---|---|---|
| String | id | The ID of the time zone to return. This must be one of the IDs returned by GetIds(). |
Returns
| Type | Description |
|---|---|
| DateTimeZone | The DateTimeZone for the given ID. (The value returned is never null.) |
Remarks
Note that this is permitted to 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.
It is advised that sources should document their behaviour regarding any fixed-offset timezones (i.e. "UTC" and "UTC+/-Offset") that are included in the list returned by GetIds(). (These IDs will not be requested by DateTimeZoneCache, but any users calling into the source directly may care.)
The source need not attempt to cache time zones; caching is typically provided by DateTimeZoneCache.
Exceptions
| Type | Condition |
|---|---|
| ArgumentException | id is not supported by this source. |
| ArgumentNullException | id is null. |
GetIds()
Declaration
IEnumerable<string> GetIds()Returns
| Type | Description |
|---|---|
| IEnumerable<String> | The IDs available from this source. (The value returned is never null.) |
Remarks
Every value in this enumeration must return a valid time zone from ForId(String) for the life of the source. The enumeration may be empty, but must not be null, and must not contain any elements which are null. It should not contain duplicates: this is not enforced, and while it may not have a significant impact on clients in some cases, it is generally unfriendly. The built-in implementations never return duplicates.
The source is not required to provide the IDs in any particular order, although they should be distinct.
Note that this list may optionally contain any of the fixed-offset timezones (with IDs "UTC" and "UTC+/-Offset"), but there is no requirement they be included.
GetSystemDefaultId()
Declaration
string GetSystemDefaultId()Returns
| Type | Description |
|---|---|
| String | The ID for the system default time zone for this source, or null if the system default time zone has no mapping in this source. |