Class TZLookup

Namespace

TZFinder

Assembly

TZFinder.dll

Provides static methods and properties for looking up time zones based on geographic coordinates. Handles loading and accessing time zone data from a file or stream, and exposes methods for querying and traversing the time zone tree.

public static class TZLookup

Inheritance

object

TZLookup

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

DataFileName

The default file name for the time zone data file.

public const string DataFileName = "TZFinder.TimeZoneData.bin"

Field Value

string

EmbeddedResourceMoniker

The moniker used to indicate that the time zone data should be loaded from an embedded resource. The name of the resource must be appended.

public const string EmbeddedResourceMoniker = "embedded://"

Field Value

string

Properties

TimeZoneDataPath

Gets or sets the file path to the time zone data file. Must be set before the time zone tree is loaded. If not set, the default path is determined automatically.

public static string TimeZoneDataPath { get; set; }

Property Value

string

TimeZoneDataStream

Gets or sets the stream containing time zone data. Must be set before the time zone tree is loaded.

public static Stream? TimeZoneDataStream { get; set; }

Property Value

Stream

Remarks

The stream gets disposed after reading the file.

Exceptions

InvalidOperationException

Thrown if the time zone tree has already been loaded.

ArgumentNullException

Thrown if the value is null.

ArgumentException

Thrown if the stream is not readable.

TimeZoneIds

Gets a read-only collection of all available time zone identifiers.

public static ReadOnlyCollection<string> TimeZoneIds { get; }

Property Value

ReadOnlyCollection<string>

TimeZoneTree

Gets the singleton instance of the TimeZoneTree used for time zone lookups. The tree is loaded lazily from the configured data file or stream on first access.

public static TimeZoneTree TimeZoneTree { get; }

Property Value

TimeZoneTree

Methods

CalculateEtcTimeZoneId(float)

Calculates the etcetera time zone identifier for the specified longitude.

public static string CalculateEtcTimeZoneId(float longitude)

Parameters

longitude float

The longitude in degrees.

Returns

string

The etcetera time zone identifier (e.g., "Etc/GMT", "Etc/GMT+2").

Exceptions

ArgumentOutOfRangeException

Thrown if longitude is out of range.

EnsureLoadedAsync()

Ensures that the time zone tree is loaded asynchronously. This method triggers the lazy loading of the time zone data if it has not already been loaded.

public static Task EnsureLoadedAsync()

Returns

Task

A Task that completes when the time zone tree has been loaded.

GetAllTimeZoneIds(float, float, out BBox, out TimeZoneIndex)

Gets all time zone identifiers for the specified longitude and latitude, including any overlapping time zones.

public static IEnumerable<string> GetAllTimeZoneIds(float longitude, float latitude, out BBox box, out TimeZoneIndex index)

Parameters

longitude float

The longitude in degrees.

latitude float

The latitude in degrees.

box BBox

When this method returns, contains the bounding box that includes the specified coordinates.

index TimeZoneIndex

When this method returns, contains the TimeZoneIndex corresponding to the specified coordinates.

Returns

IEnumerable<string>

An IEnumerable<T> of time zone identifiers for the specified coordinates. If the location is in an area with overlapping time zones, all relevant identifiers are returned.

Exceptions

ArgumentOutOfRangeException

Thrown if longitude or latitude is out of range.

GetTimeZoneId(short)

Gets the time zone identifier for the specified 1-based index.

public static string GetTimeZoneId(short index)

Parameters

index short

The 1-based index of the time zone identifier to retrieve.

Returns

string

The time zone identifier corresponding to the specified index.

Exceptions

ArgumentOutOfRangeException

Thrown if index is less than or equal to 0, or greater than to the number of available time zone identifiers.

GetTimeZoneId(float, float)

Gets the time zone identifier for the specified longitude and latitude.

public static string GetTimeZoneId(float longitude, float latitude)

Parameters

longitude float

The longitude in degrees.

latitude float

The latitude in degrees.

Returns

string

The time zone identifier for the specified coordinates.

Exceptions

ArgumentOutOfRangeException

Thrown if longitude or latitude is out of range.

GetTimeZoneId(float, float, out BBox)

Gets the time zone identifier for the specified longitude and latitude, and outputs the bounding box containing the coordinates.

public static string GetTimeZoneId(float longitude, float latitude, out BBox box)

Parameters

longitude float

The longitude in degrees.

latitude float

The latitude in degrees.

box BBox

When this method returns, contains the bounding box that includes the specified coordinates.

Returns

string

The time zone identifier for the specified coordinates.

Exceptions

ArgumentOutOfRangeException

Thrown if longitude or latitude is out of range.

GetTimeZoneIndex(float, float)

Gets the TimeZoneIndex for the specified longitude and latitude.

public static TimeZoneIndex GetTimeZoneIndex(float longitude, float latitude)

Parameters

longitude float

The longitude in degrees.

latitude float

The latitude in degrees.

Returns

TimeZoneIndex

The TimeZoneIndex corresponding to the specified geographic coordinates.

Exceptions

ArgumentOutOfRangeException

Thrown if longitude or latitude is out of range.

GetTimeZoneIndex(float, float, out BBox)

Gets the TimeZoneIndex for the specified longitude and latitude, and outputs the bounding box containing the coordinates.

public static TimeZoneIndex GetTimeZoneIndex(float longitude, float latitude, out BBox box)

Parameters

longitude float

The longitude in degrees.

latitude float

The latitude in degrees.

box BBox

When this method returns, contains the bounding box that includes the specified coordinates.

Returns

TimeZoneIndex

The TimeZoneIndex for the specified coordinates.

Exceptions

ArgumentOutOfRangeException

Thrown if longitude or latitude is out of range.

GetTimeZoneIndex(string)

Gets the 1-based index of the specified time zone identifier.

public static short GetTimeZoneIndex(string timeZoneId)

Parameters

timeZoneId string

The time zone identifier to look up.

Returns

short

The 1-based index of the specified time zone identifier.

Exceptions

ArgumentNullException

Thrown if timeZoneId is null

ArgumentException

Thrown if the specified time zone identifier is unknown.

Traverse(float, float, Action<BBox>)

Traverses all bounding boxes contained in the time zone specified by the coordinates and invokes the provided action for each.

public static void Traverse(float longitude, float latitude, Action<BBox> action)

Parameters

longitude float

The longitude in degrees.

latitude float

The latitude in degrees.

action Action<BBox>

The action to invoke for each bounding box.

Remarks

If the specified coordinates point to an area with overlapping time zones, only boxes with the same combination are traversed.

Exceptions

ArgumentNullException

Thrown if action is null.

ArgumentOutOfRangeException

Thrown if longitude or latitude is out of range.

Traverse(string, Action<BBox>)

Traverses the bounding boxes contained in the specified time zone and invokes the provided action for each.

public static void Traverse(string timeZoneId, Action<BBox> action)

Parameters

timeZoneId string

The time zone identifier.

action Action<BBox>

The action to invoke for each bounding box.

Exceptions

ArgumentNullException

Thrown if action is null.

ArgumentNullException

Thrown if timeZoneId is null

ArgumentException

Thrown if the time zone identifier is unknown.

Traverse(TimeZoneIndex, Action<BBox>)

Traverses the bounding boxes contained in the specified TimeZoneIndex and invokes the provided action for each.

public static void Traverse(TimeZoneIndex timeZoneIndex, Action<BBox> action)

Parameters

timeZoneIndex TimeZoneIndex

The TimeZoneIndex specifying the time zone(s) to traverse.

action Action<BBox>

The action to invoke for each bounding box.

Exceptions

ArgumentNullException

Thrown if action is null.