# `Localize.Territory.Subdivision`
[🔗](https://github.com/elixir-localize/localize/blob/v0.9.0/lib/localize/territory/subdivision.ex#L1)

Territory subdivision localization functions.

Subdivisions are administrative divisions within a territory, such as
states, provinces, regions, or counties. They are identified by ISO
3166-2 codes (lowercase atoms like `:caon` for Ontario, Canada or
`:gbeng` for England, United Kingdom).

### Lookup functions

This module provides three related but distinct functions for
discovering subdivisions. Understanding the difference between them
is important:

* `known_subdivisions/1` — takes a **locale**, returns a map of every
  subdivision code to its display name in that locale. Answers:
  "what subdivisions can I display in Japanese?"

* `available_subdivisions/1` — takes a **locale**, returns the sorted
  list of subdivision codes that have translations in that locale.
  This is just the keys of `known_subdivisions/1`. Answers: "which
  subdivision codes does my locale's data cover?"

* `for_territory/1` — takes a **territory**, returns the structural
  subdivisions that belong to that territory from CLDR supplemental
  data. Independent of any locale. Answers: "what are the provinces
  of Canada?"

The first two are locale-scoped (different locales may have different
sets of translated subdivisions). The third is territory-scoped
(the structural hierarchy of administrative divisions is the same
regardless of which locale is asking).

### Display names

* `display_name/2` returns the localized name for a single subdivision
  code in a specified locale.

# `available_subdivisions`

```elixir
@spec available_subdivisions(Keyword.t()) :: {:ok, [atom()]} | {:error, Exception.t()}
```

Returns the sorted list of subdivision codes that have translations
in a given locale.

Equivalent to the keys of `known_subdivisions/1`, sorted.

For the structural subdivisions of a specific territory regardless
of locale, use `for_territory/1`.

### Arguments

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is
  `Localize.get_locale()`.

### Returns

* `{:ok, codes}` where `codes` is a sorted list of subdivision
  code atoms.

* `{:error, exception}` if the locale cannot be resolved.

### Examples

    iex> {:ok, codes} = Localize.Territory.Subdivision.available_subdivisions(locale: :en)
    iex> :caon in codes
    true

# `display_name`

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

Returns the localized display name for a subdivision code.

### Arguments

* `subdivision` is a subdivision code atom or string
  (e.g., `"usca"`, `"gbcma"`, `:caon`).

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is
  `Localize.get_locale()`.

### Returns

* `{:ok, name}` where `name` is the localized subdivision name.

* `{:error, exception}` if the subdivision is unknown or the
  locale has no translation for it.

### Examples

    iex> Localize.Territory.Subdivision.display_name(:caon, locale: :en)
    {:ok, "Ontario"}

    iex> Localize.Territory.Subdivision.display_name("gbcma", locale: :en)
    {:ok, "Cumbria"}

# `display_name!`

```elixir
@spec display_name!(atom() | String.t(), Keyword.t()) :: String.t()
```

Same as `display_name/2` but raises on error.

### Examples

    iex> Localize.Territory.Subdivision.display_name!(:caon, locale: :en)
    "Ontario"

# `for_territory`

```elixir
@spec for_territory(atom() | String.t() | Localize.LanguageTag.t()) ::
  {:ok, [atom()]} | {:error, Exception.t()}
```

Returns the structural subdivisions of a territory.

Returns the administrative subdivisions that belong to a territory
according to CLDR supplemental data. This is locale-independent —
the structural hierarchy is the same regardless of which locale is
asking.

For the set of subdivisions that have translations in a specific
locale, use `known_subdivisions/1` or `available_subdivisions/1`.

### Arguments

* `territory` is a territory code atom (e.g. `:CA`), a territory
  code string (e.g. `"CA"`), or a `t:Localize.LanguageTag.t/0`
  from which the territory is derived via
  `Localize.Territory.territory_from_locale/1`.

### Returns

* `{:ok, [atom()]}` — a list of subdivision code atoms.

* `{:error, exception}` if the territory is not known.

### Examples

    iex> {:ok, subdivisions} = Localize.Territory.Subdivision.for_territory(:GB)
    iex> :gbeng in subdivisions
    true

    iex> {:ok, subdivisions} = Localize.Territory.Subdivision.for_territory("CA")
    iex> :caon in subdivisions
    true

# `known_subdivisions`

```elixir
@spec known_subdivisions(Keyword.t()) ::
  {:ok, %{required(atom()) => String.t()}} | {:error, Exception.t()}
```

Returns a map of every subdivision code to its display name in a
given locale.

The returned map contains an entry for every subdivision that has a
translation in the locale's data. This is locale-scoped — different
locales cover different sets of subdivisions depending on which
translations CLDR has for that locale.

For the structural subdivisions of a specific territory regardless
of locale, use `for_territory/1`.

### Arguments

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is
  `Localize.get_locale()`.

### Returns

* `{:ok, subdivisions}` where `subdivisions` is a map of
  subdivision code atoms to localized name strings.

* `{:error, exception}` if the locale cannot be resolved.

### Examples

    iex> {:ok, subdivisions} = Localize.Territory.Subdivision.known_subdivisions(locale: :en)
    iex> Map.get(subdivisions, :caon)
    "Ontario"

    iex> {:ok, subdivisions} = Localize.Territory.Subdivision.known_subdivisions(locale: :fr)
    iex> Map.get(subdivisions, :gbeng)
    "Angleterre"

---

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