Calendrical.TimeZone (Calendrical v2.2.0)

Copy Markdown

Resolves a time zone as a locale writes it, with the date and time written with it, to a DateTime.t/0.

resolve/3 is Localize's Localize.DateTime.Timezone.resolve/3, which reads every form a locale writes a zone in: ISO 8601 and localized GMT offsets (+05:30, GMT+2, UTC−4), IANA names (Asia/Tokyo), and CLDR's names and abbreviations of zones and metazones (Pacific Time, EST, Mitteleuropäische Zeit). A zone's offset on the date comes from the time zone database the application configures.

A name of standard or daylight time keeps its own offset, as ICU reads it: 2024-07-15 14:00 EST is 14:00 at -05:00, since New York keeps daylight time in July. Any other form follows the zone's clock, and a wall time its clocks pass twice is read in standard time, one they skip at the offset before the change, as ICU reads them.

Summary

Functions

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

Resolves a time zone as a locale writes it, at a date and time, to the DateTime.t/0 it names, as Localize.DateTime.Timezone.resolve/3 does.

tz_database()

Returns the time-zone database module, or nil when none is configured and no known implementation is loaded.

Functions

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

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

Resolves a time zone as a locale writes it, at a date and time, to the DateTime.t/0 it names, as Localize.DateTime.Timezone.resolve/3 does.

Arguments

  • zone_string is the zone as written ("PST", "+0530", "Asia/Tokyo", "Pacific Time").

  • naive_datetime is the date and time written with it, a NaiveDateTime.t/0.

  • options is a keyword list of options.

Options

Returns

  • {:ok, datetime}, or

  • {:error, exception} when the string is not a zone the locale writes, or names a time zone the configured database does not resolve.

Examples

iex> {:ok, datetime} = Calendrical.TimeZone.resolve("Asia/Tokyo", ~N[2024-07-15 14:00:00])
iex> {datetime.zone_abbr, datetime.utc_offset}
{"JST", 32400}

iex> {:ok, datetime} = Calendrical.TimeZone.resolve("Pacific Time", ~N[2024-07-15 14:00:00])
iex> {datetime.time_zone, datetime.zone_abbr}
{"America/Los_Angeles", "PDT"}

iex> {:ok, datetime} = Calendrical.TimeZone.resolve("EST", ~N[2024-07-15 14:00:00])
iex> {DateTime.to_naive(datetime), datetime.utc_offset + datetime.std_offset}
{~N[2024-07-15 14:00:00], -18000}

iex> {:ok, datetime} = Calendrical.TimeZone.resolve("Mitteleuropäische Zeit", ~N[2024-07-15 14:00:00], locale: :de)
iex> datetime.time_zone
"Europe/Berlin"

iex> {:error, %Localize.UnknownTimezoneError{}} =
...>   Calendrical.TimeZone.resolve("Middle Earth Time", ~N[2024-07-15 14:00:00])

tz_database()

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

Returns the time-zone database module, or nil when none is configured and no known implementation is loaded.

The database resolves, in order, from:

  1. The :elixir :time_zone_database application environment (config :elixir, :time_zone_database, Tz.TimeZoneDatabase) — Elixir's own UTC-only default is treated as "not configured".

  2. Tz.TimeZoneDatabase or Tzdata.TimeZoneDatabase when the respective library is loaded (Tz is preferred when both are available).

Consumers that want IANA name resolution should add a Calendar.TimeZoneDatabase implementation to their dependency list and configure it. The resolver works without one but rejects IANA names.

Returns

Examples

iex> Calendrical.TimeZone.tz_database()
Tz.TimeZoneDatabase