# `Localize.DateTime.Timezone`
[🔗](https://github.com/elixir-localize/localize/blob/v0.38.0/lib/localize/datetime/timezone.ex#L1)

Provides timezone data access and timezone formatting for CLDR
date/time format symbols.

This module combines CLDR short zone code lookups (mapping between
BCP 47 timezone identifiers and IANA timezone names) with the format
symbol handlers for `z`, `Z`, `O`, `v`, `V`, `X`, and `x`.

# `fetch_short_zone`

```elixir
@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

# `get_short_zone`

```elixir
@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

# `gmt_format`

```elixir
@spec gmt_format(map(), atom(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

# `iso_format`

```elixir
@spec iso_format(map(), Keyword.t()) :: {:ok, String.t()}
```

# `non_location_format`

```elixir
@spec non_location_format(map(), atom(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

# `territories_by_timezone`

```elixir
@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

# `timezone_count_for_territory`

```elixir
@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

# `timezones`

```elixir
@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}

# `timezones_by_territory`

```elixir
@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

# `timezones_for_territory`

```elixir
@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

# `validate_short_zone`

```elixir
@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"}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*