@spec fetch_short_zone(String.t()) :: {:ok, map()} | {:error, Exception.t()}

Returns {:ok, map} for a given CLDR short zone code, or :error if no such short code exists.

Arguments

• short_zone is a CLDR short timezone code string.

Returns

• {:ok, map} where map has :aliases, :preferred, and :territory keys.

• {:error, exception} if the short zone code is not found.

Examples

iex> Localize.DateTime.Timezone.fetch_short_zone("ausyd")
{
  :ok,
  %{
    preferred: nil,
    aliases: ["Australia/Sydney", "Australia/ACT", "Australia/Canberra", "Australia/NSW"],
    territory: :AU
  }
}

iex> match?({:error, _}, Localize.DateTime.Timezone.fetch_short_zone("nope"))
true

@spec get_short_zone(String.t(), term()) :: map() | term()

Returns a timezone map for a given CLDR short zone code, or a default value.

Arguments

• short_zone is a CLDR short timezone code string.

• default is the value to return if the short zone is not found. Defaults to nil.

Returns

• A map with :aliases, :preferred, and :territory keys, or the default value.

Examples

iex> Localize.DateTime.Timezone.get_short_zone("ausyd")
%{
  preferred: nil,
  aliases: ["Australia/Sydney", "Australia/ACT", "Australia/Canberra", "Australia/NSW"],
  territory: :AU
}

iex> Localize.DateTime.Timezone.get_short_zone("nope")
nil

@spec territories_by_timezone() :: %{required(String.t()) => atom()}

Returns a mapping of IANA time zone names to their known territory.

A time zone can only belong to one territory in CLDR.

Returns

• A map where each key is an IANA timezone string and each value is a territory atom.

Examples

iex> territories = Localize.DateTime.Timezone.territories_by_timezone()
iex> Map.get(territories, "Australia/Sydney")
:AU

@spec timezone_count_for_territory(atom()) ::
  {:ok, non_neg_integer()} | {:error, Exception.t()}

Returns the count of timezones for a given territory.

Arguments

• territory is a territory atom like :US or :AU.

Returns

• {:ok, count} where count is the number of timezones.

• {:error, exception} if the territory has no known timezones.

Examples

iex> {:ok, count} = Localize.DateTime.Timezone.timezone_count_for_territory(:AU)
iex> count > 0
true

@spec timezones() :: %{required(String.t()) => map()}

Returns a mapping of CLDR short zone codes to IANA timezone names.

Each key is a BCP 47 short timezone identifier string and each value is a map with :aliases, :preferred, and :territory keys.

Returns

• A map of %{String.t() => map()}.

Examples

iex> timezones = Localize.DateTime.Timezone.timezones()
iex> Map.get(timezones, "ausyd")
%{preferred: nil, aliases: ["Australia/Sydney", "Australia/ACT", "Australia/Canberra", "Australia/NSW"], territory: :AU}

@spec timezones_by_territory() :: %{
  required(atom()) => [
    %{
      short_zone: String.t(),
      territory: atom(),
      aliases: [term(), ...],
      preferred: nil | String.t()
    },
    ...
  ]
}

Returns a mapping of territories to their known IANA timezone names.

Returns

• A map where each key is a territory atom and each value is a list of timezone maps including :short_zone, :aliases, :preferred, and :territory keys.

Examples

iex> {:ok, zones} = Localize.DateTime.Timezone.timezones_for_territory(:AU)
iex> Enum.any?(zones, & &1.short_zone == "ausyd")
true

@spec timezones_for_territory(atom()) :: {:ok, [map()]} | {:error, Exception.t()}

Returns a list of timezone maps for a given territory.

Arguments

• territory is a territory atom like :US or :AU.

Returns

• {:ok, list} where list is timezone maps for the territory.

• {:error, exception} if the territory has no known timezones.

Examples

iex> {:ok, zones} = Localize.DateTime.Timezone.timezones_for_territory(:US)
iex> is_list(zones)
true

@spec validate_short_zone(String.t()) :: {:ok, String.t()} | {:error, Exception.t()}

Validates a CLDR short zone code and returns the canonical IANA timezone name.

Arguments

• short_zone is a CLDR short timezone code string.

Returns

• {:ok, iana_name} where iana_name is the canonical IANA timezone name string.

• {:error, exception} if the short zone code is not valid.

Examples

iex> Localize.DateTime.Timezone.validate_short_zone("ausyd")
{:ok, "Australia/Sydney"}

iex> Localize.DateTime.Timezone.validate_short_zone("nope")
{:error, %Localize.UnknownTimezoneError{timezone: "nope"}}