Search documentation of Localize

# Localize.DateTime.Timezone (Localize v0.39.0)

Copy Markdown View Source

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`.

## Summary

### Functions

fetch_short_zone(short_zone)

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

get_short_zone(short_zone, default \\ nil)

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

gmt_format(datetime, locale_id, options \\ [])
iso_format(datetime, options \\ [])
non_location_format(datetime, locale_id, options \\ [])
territories_by_timezone()

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

timezone_count_for_territory(territory)

Returns the count of timezones for a given territory.

timezones()

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

timezones_by_territory()

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

timezones_for_territory(territory)

Returns a list of timezone maps for a given territory.

validate_short_zone(short_zone)

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

## Functions

# fetch_short_zone(short_zone)

    @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(short_zone, default \\ nil)

    @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(datetime, locale_id, options \\ [])

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

# iso_format(datetime, options \\ [])

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

# non_location_format(datetime, locale_id, options \\ [])

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

# territories_by_timezone()

    @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(territory)

    @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()

    @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()

    @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(territory)

    @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(short_zone)

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