Calendrical.TimeZone (Calendrical v0.5.0)

Copy Markdown

Resolve textual time-zone identifiers captured by the parser into UTC offsets.

The resolver tries these strategies in order:

  1. ISO 8601 offset — Z, ±HHMM, ±HH:MM, ±HH:MM:SS.

  2. GMT/UTC format — GMT, GMT+10, UTC-5:30.

  3. IANA region/city — Asia/Tokyo, America/New_York. Looked up via the host application's installed time-zone database (Tzdata or Tz) — whichever is loaded at runtime. If neither is loaded, IANA names are rejected (consumer should add :tzdata or :tz as a dependency to support them).

  4. Short abbreviation — PST, EST, JST. Resolved via a small static table for the most common abbreviations. Note that abbreviations are inherently ambiguous (CST could be Central or China Standard); the table picks the most common North-American/Asian/European reading.

  5. CLDR locale name — Pacific Time, Greenwich Mean Time. Looked up via Localize's CLDR timeZoneNames data for the parsing locale.

When the parser captures a wall-clock instant alongside an IANA zone, the resolver uses the instant to pick between standard / daylight offsets (e.g. 2024-07-15 14:00 America/New_York → EDT (-04:00), while 2024-01-15 14:00 America/New_York → EST (-05:00)).

Summary

Functions

resolve(zone_string, naive_dt, options \\ [])

Resolves zone_string against a wall-clock NaiveDateTime.

tz_database()

Returns the configured time-zone database module, or nil when neither Tzdata nor Tz is loaded.

Functions

resolve(zone_string, naive_dt, options \\ [])

@spec resolve(String.t(), NaiveDateTime.t(), Keyword.t()) ::
  {:ok, DateTime.t()} | {:error, atom() | Exception.t()}

Resolves zone_string against a wall-clock NaiveDateTime.

Arguments

  • zone_string is the captured zone token (e.g. "PST", "+0530", "Asia/Tokyo", "Pacific Time").

  • naive_dt is the parsed wall-clock instant. Used to disambiguate standard vs daylight offsets for IANA zones (e.g. America/New_York is -05:00 in January and -04:00 in July).

  • options is a keyword list of options.

Options

  • :locale — locale to use when looking up CLDR-style names like "Pacific Time". Defaults to Localize.get_locale/0.

Returns

  • {:ok, DateTime.t()} when the zone resolves.

  • {:error, reason} when the zone string isn't recognizable.

tz_database()

@spec tz_database() :: module() | nil

Returns the configured time-zone database module, or nil when neither Tzdata nor Tz is loaded.

Consumers that want IANA name resolution should add one of these to their dependency list. The resolver works without them but rejects IANA names.