@spec get_canonical!(
  zone_name :: String.t(),
  instant :: DateTime.t(),
  opts :: Keyword.t()
) ::
  Zonex.Zone.t() | no_return()

Gets a zone for a given IANA time zone name and raises if not found.

If the time zone is an alias (not canonical), the canonical zone will be returned instead. This includes legacy aliases such as "CET".

Since names and UTC offsets vary depending on time of year (due to daylight saving time), you need to specify the instant at which the time zone should be expressed.

options

Options

• :locale is any locale or locale name validated by Cldr.validate_locale/2. The default is Cldr.get_locale() which returns the locale set for the current process

@spec get_canonical(
  zone_name :: String.t(),
  instant :: DateTime.t(),
  opts :: Keyword.t()
) ::
  {:ok, Zonex.Zone.t()} | {:error, :zone_not_found}

Gets a zone for a given IANA time zone name.

If the time zone is an alias (not canonical), the canonical zone will be returned instead. This includes legacy aliases such as "CET", which Tzdata links to a canonical Olson name.

Since names and UTC offsets vary depending on time of year (due to daylight saving time), you need to specify the instant at which the time zone should be expressed.

options

Options

• :locale is any locale or locale name validated by Cldr.validate_locale/2. The default is Cldr.get_locale() which returns the locale set for the current process

@spec legacy?(zone_name :: Calendar.time_zone()) :: boolean()

Determines if a zone name is legacy.

iex> Zonex.legacy?("America/Chicago")
false

iex> Zonex.legacy?("WET")
true

@spec list_canonical(instant :: DateTime.t(), opts :: Keyword.t()) :: [Zonex.Zone.t()]

Lists all canonical time zones from the IANA database.

Since names and UTC offsets vary depending on time of year (due to daylight saving time), you need to specify the instant at which the time zone should be expressed.

options

Options

• :locale is any locale or locale name validated by Cldr.validate_locale/2. The default is Cldr.get_locale() which returns the locale set for the current process

@spec observes_dst?(zone_name :: Calendar.time_zone(), year :: integer()) :: boolean()

Determines if a zone observes daylight saving time at any point during a calendar year (in UTC).

Unlike the dst field on Zonex.Zone, which is whether daylight saving time is in effect at a given instant, this covers the whole year. In January, America/Denver and America/Phoenix both have dst: false, but only America/Denver observes daylight saving time.

Returns false for unknown zone names.

iex> Zonex.observes_dst?("America/Denver", 2026)
true

iex> Zonex.observes_dst?("America/Phoenix", 2026)
false