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

Provides territory and subdivision localization functions
built on the Unicode CLDR repository.

Territory display names, subdivision names, and translation
between locales are loaded on demand from the locale data
provider. Territory metadata (GDP, population, currency,
measurement system, language population) is loaded from
supplemental data.

## Styles

Territory display names come in three styles:

* `:standard` — the full display name (default).

* `:short` — a shorter form when available (e.g., "US"
  instead of "United States").

* `:variant` — an alternative form when available (e.g.,
  "Congo (Republic)" instead of "Congo - Brazzaville").

# `available_styles`

```elixir
@spec available_styles() :: [:short | :standard | :variant, ...]
```

Returns the list of available territory display name styles.

### Returns

* `[:short, :standard, :variant]`.

### Examples

    iex> Localize.Territory.available_styles()
    [:short, :standard, :variant]

# `children`

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

Returns the child territories for a given territory.

### Arguments

* `territory` is a territory code atom, string, or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, children}` where `children` is a list of child
  territory atoms.

* `{:error, exception}` if the territory is unknown or has
  no children.

### Examples

    iex> {:ok, children} = Localize.Territory.children(:EU)
    iex> :FR in children
    true

# `children!`

```elixir
@spec children!(atom() | String.t() | Localize.LanguageTag.t()) :: [atom()]
```

Same as `children/1` but raises on error.

### Examples

    iex> children = Localize.Territory.children!(:EU)
    iex> :DE in children
    true

# `contains?`

```elixir
@spec contains?(atom() | Localize.LanguageTag.t(), atom() | Localize.LanguageTag.t()) ::
  boolean()
```

Checks if a parent territory contains a child territory.

### Arguments

* `parent_territory` is a territory code atom.

* `child_territory` is a territory code atom.

### Returns

* `true` if the parent contains the child.

* `false` otherwise.

### Examples

    iex> Localize.Territory.contains?(:EU, :DK)
    true

    iex> Localize.Territory.contains?(:DK, :EU)
    false

# `default_territory`

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

Returns the default territory for a locale.

Extracts the territory from a locale's language tag. If the
locale does not have an explicit territory, the likely subtag
data is used to infer one.

### Arguments

* `locale` is a locale identifier atom, string, or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, territory_atom}` where `territory_atom` is the
  inferred territory.

* `{:error, exception}` if the locale is not valid.

### Examples

    iex> Localize.Territory.default_territory(:en)
    {:ok, :US}

    iex> Localize.Territory.default_territory(:ja)
    {:ok, :JP}

# `display_name`

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

Returns the localized display name for a territory code.

### Arguments

* `territory` is a territory code atom, string, or a
  `t:Localize.LanguageTag.t/0`.

* `options` is a keyword list of options.

### Options

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

* `:style` is one of `:short`, `:standard`, or `:variant`.
  The default is `:standard`.

### Returns

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

* `{:error, exception}` if the territory is unknown, the
  locale cannot be loaded, or the style is not available.

### Examples

    iex> Localize.Territory.display_name(:GB)
    {:ok, "United Kingdom"}

    iex> Localize.Territory.display_name(:GB, style: :short)
    {:ok, "UK"}

    iex> Localize.Territory.display_name(:GB, locale: :pt)
    {:ok, "Reino Unido"}

# `display_name!`

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

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

### Examples

    iex> Localize.Territory.display_name!(:GB)
    "United Kingdom"

    iex> Localize.Territory.display_name!(:GB, style: :short)
    "UK"

# `individual_territories`

```elixir
@spec individual_territories() :: [atom()]
```

Returns a sorted list of territory codes for individual
territories.

Only leaf territories are returned — those contained by a
continental or sub-continental region. Macro-regions and
groupings (e.g., `:"001"` World, `:"150"` Europe) are
excluded.

To retrieve the full map of ISO 3166 code mappings
(Alpha-2, Alpha-3, numeric) for all territories, see
`territory_codes/0`.

### Returns

* A sorted list of territory code atoms.

### Examples

    iex> codes = Localize.Territory.individual_territories()
    iex> :US in codes
    true

    iex> codes = Localize.Territory.individual_territories()
    iex> :"001" in codes
    false

# `info`

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

Returns metadata for a territory including GDP, population,
currency, measurement system, and language population data.

### Arguments

* `territory` is a territory code atom, string, or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, info_map}` on success.

* `{:error, exception}` if the territory is unknown or has
  no metadata available.

### Examples

    iex> {:ok, info} = Localize.Territory.info(:US)
    iex> info.gdp
    24660000000000

    iex> {:ok, info} = Localize.Territory.info(:US)
    iex> info.population
    341963000

# `info!`

```elixir
@spec info!(atom() | String.t() | Localize.LanguageTag.t()) :: map()
```

Same as `info/1` but raises on error.

### Examples

    iex> info = Localize.Territory.info!(:US)
    iex> info.literacy_percent
    99

# `normalize_name`

```elixir
@spec normalize_name(String.t()) :: String.t()
```

Normalizes a territory or subdivision name for matching.

Downcases the string, removes ` & ` and `.`, and collapses
whitespace.

### Arguments

* `name` is a territory or subdivision name string.

### Returns

* A normalized string.

### Examples

    iex> Localize.Territory.normalize_name("Congo - Brazzaville")
    "congo - brazzaville"

# `parent`

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

Returns the parent territories for a given territory.

### Arguments

* `territory` is a territory code atom, string, or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, parents}` where `parents` is a sorted list of
  parent territory atoms.

* `{:error, exception}` if the territory is unknown or has
  no parents.

### Examples

    iex> Localize.Territory.parent(:GB)
    {:ok, [:"154", :UN]}

    iex> Localize.Territory.parent(:FR)
    {:ok, [:"155", :EU, :EZ, :UN]}

# `parent!`

```elixir
@spec parent!(atom() | String.t() | Localize.LanguageTag.t()) :: [atom(), ...]
```

Same as `parent/1` but raises on error.

### Examples

    iex> Localize.Territory.parent!(:GB)
    [:"154", :UN]

# `subdivision_name`

```elixir
@spec subdivision_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_name(:caon, locale: :en)
    {:ok, "Ontario"}

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

# `subdivision_name!`

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

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

### Examples

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

# `territory_chain`

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

Returns the territory fallback chain for a territory.

The chain starts with the territory itself and includes each
containing territory in order of increasing scope, ending with
`:"001"` (the world).

### Arguments

* `territory` is a territory code atom, string, or integer.

### Returns

* `{:ok, chain}` where `chain` is a list of territory atoms.

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

### Examples

    iex> Localize.Territory.territory_chain(:US)
    {:ok, [:US, :UN, :"001"]}

    iex> Localize.Territory.territory_chain(:"001")
    {:ok, [:"001"]}

# `territory_codes`

```elixir
@spec territory_codes() :: %{required(atom()) => map()}
```

Returns a map of territory codes (ISO 3166 Alpha-2) to their
Alpha-3, FIPS 10, and numeric code equivalents.

### Returns

* A map of `%{territory_atom => %{alpha3: string, ...}}`.

### Examples

    iex> codes = Localize.Territory.territory_codes()
    iex> Map.get(codes, :US)
    %{alpha3: "USA", numeric: "840"}

# `territory_from_locale`

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

Returns the effective territory for a locale.

Resolves the territory using the following precedence:

1. The `rg` (region override) Unicode extension parameter,
   if present (e.g., `"en-US-u-rg-gbzzzz"` → `:GB`).

2. The explicit territory in the language tag (e.g.,
   `"en-AU"` → `:AU`).

3. The territory inferred from likely subtags via
   `Localize.validate_locale/1` (e.g., `"en"` → `:US`,
   `"de"` → `:DE`).

### Arguments

* `locale` is a locale identifier string, atom, or a
  `t:Localize.LanguageTag.t/0` struct.

### Returns

* `{:ok, territory_code}` where `territory_code` is an atom.

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

### Examples

    iex> Localize.Territory.territory_from_locale("en-AU")
    {:ok, :AU}

    iex> Localize.Territory.territory_from_locale("en")
    {:ok, :US}

    iex> Localize.Territory.territory_from_locale("de")
    {:ok, :DE}

# `the_world`

```elixir
@spec the_world() :: :"001"
```

Returns the territory code representing the world.

### Returns

* The atom `:"001"`.

### Examples

    iex> Localize.Territory.the_world()
    :"001"

# `to_currency_code`

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

Returns the current (oldest active) currency code for a
territory.

### Arguments

* `territory` is a territory code atom, string, or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, currency_code}` on success.

* `{:error, exception}` if the territory has no active
  currencies.

### Examples

    iex> Localize.Territory.to_currency_code(:US)
    {:ok, :USD}

    iex> Localize.Territory.to_currency_code(:GB)
    {:ok, :GBP}

# `to_currency_code!`

```elixir
@spec to_currency_code!(atom() | String.t() | Localize.LanguageTag.t()) :: atom()
```

Same as `to_currency_code/1` but raises on error.

### Examples

    iex> Localize.Territory.to_currency_code!(:US)
    :USD

# `to_currency_codes`

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

Returns all active currency codes for a territory, sorted
by start date (oldest first).

### Arguments

* `territory` is a territory code atom, string, or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, [currency_code, ...]}` on success.

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

### Examples

    iex> Localize.Territory.to_currency_codes(:US)
    {:ok, [:USD]}

# `to_currency_codes!`

```elixir
@spec to_currency_codes!(atom() | String.t() | Localize.LanguageTag.t()) :: [atom()]
```

Same as `to_currency_codes/1` but raises on error.

### Examples

    iex> Localize.Territory.to_currency_codes!(:US)
    [:USD]

# `to_territory_code`

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

Converts a localized territory name to a territory code.

### Arguments

* `name` is a localized territory name string.

* `locale` is the locale the name is in.

### Returns

* `{:ok, territory_code}` on success.

* `{:error, exception}` if no matching territory is found.

### Examples

    iex> Localize.Territory.to_territory_code("United Kingdom", :en)
    {:ok, :GB}

    iex> Localize.Territory.to_territory_code("Reino Unido", :pt)
    {:ok, :GB}

# `to_territory_code!`

```elixir
@spec to_territory_code!(String.t(), atom() | String.t() | Localize.LanguageTag.t()) ::
  atom()
```

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

### Examples

    iex> Localize.Territory.to_territory_code!("United Kingdom", :en)
    :GB

# `translate_subdivision`

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

Translates a subdivision name from one locale to another.

### Arguments

* `name` is a localized subdivision name string.

* `from_locale` is the locale the name is in.

* `options` is a keyword list of options.

### Options

* `:to` is the target locale. The default is
  `Localize.get_locale()`.

### Returns

* `{:ok, translated_name}` on success.

* `{:error, exception}` if the name cannot be found or
  translated.

### Examples

    iex> Localize.Territory.translate_subdivision("Ontario", :en, to: :pt)
    {:ok, "Ontário"}

# `translate_subdivision!`

```elixir
@spec translate_subdivision!(
  String.t(),
  atom() | String.t() | Localize.LanguageTag.t(),
  Keyword.t()
) ::
  String.t()
```

Same as `translate_subdivision/3` but raises on error.

### Examples

    iex> Localize.Territory.translate_subdivision!("Ontario", :en, to: :pt)
    "Ontário"

# `translate_territory`

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

Translates a territory display name from one locale to another.

Looks up the territory code for the given name in `from_locale`,
then returns its display name in `to_locale`.

### Arguments

* `name` is a localized territory name string.

* `from_locale` is the locale the name is in.

* `options` is a keyword list of options.

### Options

* `:to` is the target locale. The default is
  `Localize.get_locale()`.

* `:style` is one of `:short`, `:standard`, or `:variant`.
  The default is `:standard`.

### Returns

* `{:ok, translated_name}` on success.

* `{:error, exception}` if the name cannot be found in the
  source locale or translated to the target locale.

### Examples

    iex> Localize.Territory.translate_territory("United Kingdom", :en, to: :pt)
    {:ok, "Reino Unido"}

    iex> Localize.Territory.translate_territory("Reino Unido", :pt, to: :en)
    {:ok, "United Kingdom"}

# `translate_territory!`

```elixir
@spec translate_territory!(
  String.t(),
  atom() | String.t() | Localize.LanguageTag.t(),
  Keyword.t()
) ::
  String.t()
```

Same as `translate_territory/3` but raises on error.

### Examples

    iex> Localize.Territory.translate_territory!("United Kingdom", :en, to: :pt)
    "Reino Unido"

# `unicode_flag`

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

Returns a Unicode flag emoji for a territory or locale.

Converts a two-letter ISO 3166 territory code into the
corresponding regional indicator flag emoji. Territories
that are not two-letter codes (e.g., region codes like
`:"001"`) return an empty string.

When given a `t:Localize.LanguageTag.t/0`, the territory
is extracted from the tag.

### Arguments

* `territory_or_locale` is a territory code atom, string,
  or a `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, flag_string}` where `flag_string` is the Unicode
  flag emoji, or an empty string if the territory does not
  have a flag representation.

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

### Examples

    iex> Localize.Territory.unicode_flag(:US)
    {:ok, "🇺🇸"}

    iex> Localize.Territory.unicode_flag(:GB)
    {:ok, "🇬🇧"}

    iex> Localize.Territory.unicode_flag(:"001")
    {:ok, ""}

    iex> {:ok, tag} = Localize.validate_locale(:en)
    iex> Localize.Territory.unicode_flag(tag)
    {:ok, "🇺🇸"}

# `unicode_flag!`

```elixir
@spec unicode_flag!(Localize.LanguageTag.t() | atom() | String.t()) :: String.t()
```

Same as `unicode_flag/1` but raises on error.

### Examples

    iex> Localize.Territory.unicode_flag!(:US)
    "🇺🇸"

---

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