Cldr Territories v2.1.0 Cldr.Territory View Source

Supports the CLDR Territories definitions which provide the localization of many territories.

Link to this section Summary

Functions

Returns a list of available styles.

Returns the available territories for a given locale.

Lists children(s) for the given territory code. Returns {:ok, list} if successful, otherwise {:error, reason}.

The same as children/2, but raises an exception if it fails.

Checks relationship between two territories, where the first argument is the parent and second the child. Returns true if successful, otherwise false.

Returns a list of country codes.

Localized string for the given LanguageTag.t. Returns {:ok, String.t} if successful, otherwise {:error, reason}.

Localized string for the given territory code. Returns {:ok, String.t} if successful, otherwise {:error, reason}.

Maps territory info for the given territory code. Returns {:ok, map} if successful, otherwise {:error, reason}.

The same as info/1, but raises an exception if it fails.

Returns a map of all known territories in a given locale.

Lists parent(s) for the given territory code. Returns {:ok, list} if successful, otherwise {:error, reason}.

The same as parent/2, but raises an exception if it fails.

A helper method to get a territory's currency code if a territory has multiply currencies then the oldest active currency is returned. Returns {:ok, code} if successful, otherwise {:error, reason}.

The same as to_currency_code/2, but raises an exception if it fails.

A helper method to get a territory's currency codes. Returns {:ok, list} if successful, otherwise {:error, reason}.

The same as to_currency_codes/2, but raises an exception if it fails.

Unicode flag for the given territory code. Returns {:ok, flag} if successful, otherwise {:error, reason}.

The same as to_unicode_flag/1, but raises an exception if it fails.

Translate a LanguageTag.t into a localized string from one locale to another. Returns {:ok, result} if successful, otherwise {:error, reason}.

Translate a localized string from one locale to another. Returns {:ok, result} if successful, otherwise {:error, reason}.

Link to this section Types

Specs

as_options() :: [{:as, :atom | :binary | :charlist}]
Link to this type

atom_binary_charlist()

View Source

Specs

atom_binary_charlist() :: atom() | binary() | charlist()

Specs

atom_binary_tag() :: atom() | binary() | Cldr.LanguageTag.t()

Specs

atom_tag() :: atom() | Cldr.LanguageTag.t()

Specs

binary_tag() :: binary() | Cldr.LanguageTag.t()

Specs

error() :: {module(), binary()}

Specs

options() :: [locale: binary_tag(), style: styles()]

Specs

styles() :: :short | :standard | :variant

Specs

tag() :: Cldr.LanguageTag.t()

Link to this section Functions

Specs

available_styles() :: [styles()]

Returns a list of available styles.

Example

iex> Cldr.Territory.available_styles()
[:short, :standard, :variant]
Link to this function

available_territories(backend)

View Source

Specs

available_territories(Cldr.backend()) :: [atom()]

Returns the available territories for a given locale.

Example

=> Cldr.Territory.available_territories(TestBackend.Cldr)
[:"001", :"002", :"003", :"005", :"009", :"011", :"013", :"014", :"015", :"017",
:"018", :"019", :"021", :"029", :"030", :"034", :"035", :"039", :"053", :"054",
:"057", :"061", :"142", :"143", :"145", :"150", :"151", :"154", :"155", :"202",
:"419", :AC, :AD, :AE, :AF, :AG, :AI, :AL, :AM, :AO, :AQ, :AR, :AS, :AT, :AU,
:AW, :AX, :AZ, :BA, :BB, ...]
Link to this function

children(territory_code, opts \\ [as: :atom])

View Source

Specs

children(atom_binary_tag(), as_options()) ::
  {:ok, atom_binary_charlist()} | {:error, error()}

Lists children(s) for the given territory code. Returns {:ok, list} if successful, otherwise {:error, reason}.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

iex> Cldr.Territory.children(:EU)
{:ok,
 [:AT, :BE, :CY, :CZ, :DE, :DK, :EE, :ES, :FI, :FR, :GR, :HR, :HU, :IE,
  :IT, :LT, :LU, :LV, :MT, :NL, :PL, :PT, :SE, :SI, :SK, :BG, :RO]}

iex> Cldr.Territory.children(:ZZZ)
{:error, {Cldr.UnknownTerritoryError, "The territory :ZZZ is unknown"}}

iex> Cldr.Territory.children(:GB)
{:error, {Cldr.UnknownParentError, "The territory :GB has no children"}}
Link to this function

children!(territory_code, opts \\ [as: :atom])

View Source

Specs

The same as children/2, but raises an exception if it fails.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

iex> Cldr.Territory.children!(:EU)
[:AT, :BE, :CY, :CZ, :DE, :DK, :EE, :ES, :FI, :FR, :GR, :HR, :HU, :IE, :IT,
 :LT, :LU, :LV, :MT, :NL, :PL, :PT, :SE, :SI, :SK, :BG, :RO]
Link to this function

contains?(parent, child)

View Source

Specs

contains?(atom_tag(), atom_tag()) :: boolean()

Checks relationship between two territories, where the first argument is the parent and second the child. Returns true if successful, otherwise false.

Example

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

iex> Cldr.Territory.contains?(:DK, :EU)
false
Link to this function

country_codes(opts \\ [as: :atom])

View Source

Specs

country_codes(as_options()) :: [atom_binary_charlist()]

Returns a list of country codes.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

=> Cldr.Territory.country_codes()
[:AD, :AE, :AF, :AG, :AI, :AL, :AM, :AO, :AR, :AS, :AT, :AU, :AW,
 :AX, :AZ, :BA, :BB, :BD, :BE, :BF, :BG, :BH, :BI, :BJ, :BL, :BM,
 :BN, :BO, :BQ, :BR, :BS, :BT, :BV, :BW, :BY, :BZ, :CA, :CC, :CD,
 :CF, :CG, :CH, :CI, :CK, :CL, :CM, :CN, :CO, :CR, :CU, ...]
Link to this function

from_language_tag(tag, backend, options \\ [style: :standard])

View Source

Specs

from_language_tag(tag(), Cldr.backend(), options()) ::
  {:ok, binary()} | {:error, error()}

Localized string for the given LanguageTag.t. Returns {:ok, String.t} if successful, otherwise {:error, reason}.

Example

iex> Cldr.Territory.from_language_tag(Cldr.get_locale(TestBackend.Cldr), TestBackend.Cldr)
{:ok, "World"}

iex> Cldr.Territory.from_language_tag(Cldr.get_locale(TestBackend.Cldr), TestBackend.Cldr, [style: :short])
{:error, {Cldr.UnknownStyleError, "The style :short is unknown"}}

iex> Cldr.Territory.from_language_tag(Cldr.get_locale(TestBackend.Cldr), TestBackend.Cldr, [style: :ZZZ])
{:error, {Cldr.UnknownStyleError, "The style :ZZZ is unknown"}}

iex> Cldr.Territory.from_language_tag(Cldr.get_locale(TestBackend.Cldr), TestBackend.Cldr, [style: "ZZZ"])
{:error, {Cldr.UnknownStyleError, "The style \"ZZZ\" is unknown"}}
Link to this function

from_language_tag!(tag, backend, options \\ [style: :standard])

View Source

Specs

from_language_tag!(tag(), Cldr.backend(), options()) :: binary() | no_return()

The same as from_language_tag/2, but raises an exception if it fails.

Example

iex> Cldr.Territory.from_language_tag!(Cldr.get_locale(TestBackend.Cldr), TestBackend.Cldr)
"World"
Link to this function

from_territory_code(territory_code, backend, options \\ [locale: Cldr.get_locale(), style: :standard])

View Source

Specs

from_territory_code(atom_binary_tag(), Cldr.backend(), options()) ::
  {:ok, binary()} | {:error, error()}

Localized string for the given territory code. Returns {:ok, String.t} if successful, otherwise {:error, reason}.

Example

iex> Cldr.Territory.from_territory_code(:GB, TestBackend.Cldr)
{:ok, "United Kingdom"}

iex> Cldr.Territory.from_territory_code(:GB, TestBackend.Cldr, [style: :short])
{:ok, "UK"}

iex> Cldr.Territory.from_territory_code(:GB, TestBackend.Cldr, [style: :ZZZ])
{:error, {Cldr.UnknownStyleError, "The style :ZZZ is unknown"}}

iex> Cldr.Territory.from_territory_code(:GB, TestBackend.Cldr, [style: "ZZZ"])
{:error, {Cldr.UnknownStyleError, "The style \"ZZZ\" is unknown"}}

iex> Cldr.Territory.from_territory_code(:GB, TestBackend.Cldr, [locale: "pt"])
{:ok, "Reino Unido"}

iex> Cldr.Territory.from_territory_code(:GB, TestBackend.Cldr, [locale: :zzz])
{:error, {Cldr.UnknownLocaleError, "The locale :zzz is not known."}}

iex> Cldr.Territory.from_territory_code(:GB, TestBackend.Cldr, [locale: "zzz"])
{:error, {Cldr.UnknownLocaleError, "The locale \"zzz\" is not known."}}
Link to this function

from_territory_code!(territory_code, backend, options \\ [locale: Cldr.get_locale(), style: :standard])

View Source

Specs

from_territory_code!(atom_binary_tag(), Cldr.backend(), options()) ::
  binary() | no_return()

The same as from_territory_code/2, but raises an exception if it fails.

Example

iex> Cldr.Territory.from_territory_code!(:GB, TestBackend.Cldr)
"United Kingdom"

iex> Cldr.Territory.from_territory_code!(:GB, TestBackend.Cldr, [style: :short])
"UK"

iex> Cldr.Territory.from_territory_code!(:GB, TestBackend.Cldr, [locale: "pt"])
"Reino Unido"

Specs

info(atom_tag()) :: {:ok, map()} | {:error, error()}

Maps territory info for the given territory code. Returns {:ok, map} if successful, otherwise {:error, reason}.

Example

iex> Cldr.Territory.info(:GB)
{:ok,
 %{
   currency: [GBP: %{from: ~D[1694-07-27]}],
   gdp: 2925000000000,
   language_population: %{
     "bn" => %{population_percent: 0.67},
     "cy" => %{official_status: "official_regional", population_percent: 0.77},
     "de" => %{population_percent: 6},
     "el" => %{population_percent: 0.33},
     "en" => %{official_status: "official", population_percent: 99},
     "fr" => %{population_percent: 19},
     "ga" => %{official_status: "official_regional", population_percent: 0.026},
     "gd" => %{
       official_status: "official_regional",
       population_percent: 0.099,
       writing_percent: 5
     },
     "it" => %{population_percent: 0.33},
     "ks" => %{population_percent: 0.19},
     "kw" => %{population_percent: 0.0031},
     "ml" => %{population_percent: 0.035},
     "pa" => %{population_percent: 0.79},
     "sco" => %{population_percent: 2.7, writing_percent: 5},
     "syl" => %{population_percent: 0.51},
     "yi" => %{population_percent: 0.049},
     "zh-Hant" => %{population_percent: 0.54}
   },
   literacy_percent: 99,
   measurement_system: %{
     default: :uksystem,
     paper_size: :a4,
     temperature: :uksystem
   },
   population: 65105200
 }}

Specs

info!(atom_tag()) :: map() | no_return()

The same as info/1, but raises an exception if it fails.

Example

iex> Cldr.Territory.info!(:GB)
%{
  currency: [GBP: %{from: ~D[1694-07-27]}],
  gdp: 2925000000000,
  language_population: %{
    "bn" => %{population_percent: 0.67},
    "cy" => %{official_status: "official_regional", population_percent: 0.77},
    "de" => %{population_percent: 6},
    "el" => %{population_percent: 0.33},
    "en" => %{official_status: "official", population_percent: 99},
    "fr" => %{population_percent: 19},
    "ga" => %{official_status: "official_regional", population_percent: 0.026},
    "gd" => %{
      official_status: "official_regional",
      population_percent: 0.099,
      writing_percent: 5
    },
    "it" => %{population_percent: 0.33},
    "ks" => %{population_percent: 0.19},
    "kw" => %{population_percent: 0.0031},
    "ml" => %{population_percent: 0.035},
    "pa" => %{population_percent: 0.79},
    "sco" => %{population_percent: 2.7, writing_percent: 5},
    "syl" => %{population_percent: 0.51},
    "yi" => %{population_percent: 0.049},
    "zh-Hant" => %{population_percent: 0.54}
  },
  literacy_percent: 99,
  measurement_system: %{
    default: :uksystem,
    paper_size: :a4,
    temperature: :uksystem
  },
  population: 65105200
}
Link to this function

known_territories(backend)

View Source

Specs

known_territories(Cldr.backend()) :: map()

Returns a map of all known territories in a given locale.

Example

=> Cldr.Territory.known_territories(TestBackend.Cldr)
%{SN: %{standard: "Senegal"}, "061": %{standard: "Polynesia"},
BH: %{standard: "Bahrain"}, TM: %{standard: "Turkmenistan"},
"009": %{standard: "Oceania"}, CW: %{standard: "Curaçao"},
FR: %{standard: "France"}, TN: %{standard: "Tunisia"},
FI: %{standard: "Finland"}, BF: %{standard: "Burkina Faso"},
"155": %{standard: "Western Europe"}, GL: %{standard: "Greenland"},
VI: %{standard: "U.S. Virgin Islands"}, ZW: %{standard: "Zimbabwe"},
AR: %{standard: "Argentina"}, SG: %{standard: "Singapore"},
SZ: %{standard: "Swaziland"}, ID: %{standard: "Indonesia"},
NR: %{standard: "Nauru"}, RW: %{standard: "Rwanda"},
TR: %{standard: "Turkey"}, IS: %{standard: "Iceland"},
ME: %{standard: "Montenegro"}, AW: %{standard: "Aruba"},
PY: %{standard: "Paraguay"}, "145": %{standard: "Western Asia"},
CG: %{standard: "Congo - Brazzaville", variant: "Congo (Republic)"},
LT: %{standard: "Lithuania"}, SA: %{standard: "Saudi Arabia"},
MZ: %{standard: "Mozambique"}, NU: %{standard: "Niue"},
NG: %{standard: "Nigeria"}, CK: %{standard: "Cook Islands"},
ZM: %{standard: "Zambia"}, LK: %{standard: "Sri Lanka"},
UY: %{standard: "Uruguay"}, YE: %{standard: "Yemen"},
"011": %{standard: "Western Africa"},
CC: %{standard: "Cocos (Keeling) Islands"}, BY: %{standard: "Belarus"},
IL: %{standard: "Israel"}, KY: %{standard: "Cayman Islands"},
GN: %{standard: "Guinea"}, VN: %{standard: "Vietnam"},
PE: %{standard: "Peru"}, HU: %{standard: "Hungary"},
HN: %{standard: "Honduras"}, GI: %{standard: "Gibraltar"},
"142": %{standard: "Asia"}, "029": %{...}, ...}
Link to this function

parent(territory_code, opts \\ [as: :atom])

View Source

Specs

parent(atom_binary_tag(), as_options()) ::
  {:ok, atom_binary_charlist()} | {:error, error()}

Lists parent(s) for the given territory code. Returns {:ok, list} if successful, otherwise {:error, reason}.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

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

iex> Cldr.Territory.parent(:ZZZ)
{:error, {Cldr.UnknownTerritoryError, "The territory :ZZZ is unknown"}}

iex> Cldr.Territory.parent(Cldr.get_locale())
{:error, {Cldr.UnknownChildrenError, "The territory :\"001\" has no parent(s)"}}
Link to this function

parent!(territory_code, opts \\ [as: :atom])

View Source

Specs

The same as parent/2, but raises an exception if it fails.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

iex> Cldr.Territory.parent!(:GB)
[:"154", :UN]
Link to this function

to_currency_code(territory_code, opts \\ [as: :atom])

View Source

Specs

to_currency_code(atom_binary_tag(), as_options()) ::
  {:ok, atom_binary_charlist()} | {:error, error()}

A helper method to get a territory's currency code if a territory has multiply currencies then the oldest active currency is returned. Returns {:ok, code} if successful, otherwise {:error, reason}.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

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

iex> Cldr.Territory.to_currency_code("cu")
{:ok, :CUP}
Link to this function

to_currency_code!(territory_code, opts \\ [as: :atom])

View Source

Specs

to_currency_code!(atom_binary_tag(), as_options()) ::
  atom_binary_charlist() | no_return()

The same as to_currency_code/2, but raises an exception if it fails.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

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

iex> Cldr.Territory.to_currency_code!(:US, as: :charlist)
'USD'

iex> Cldr.Territory.to_currency_code!("PS")
:ILS

iex> Cldr.Territory.to_currency_code!("PS", as: :binary)
"ILS"
Link to this function

to_currency_codes(territory_code, opts \\ [as: :atom])

View Source

Specs

to_currency_codes(atom_binary_tag(), as_options()) ::
  {:ok, [atom_binary_charlist()]} | {:error, error()}

A helper method to get a territory's currency codes. Returns {:ok, list} if successful, otherwise {:error, reason}.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

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

iex> Cldr.Territory.to_currency_codes("cu")
{:ok, [:CUP, :CUC]}
Link to this function

to_currency_codes!(territory_code, opts \\ [as: :atom])

View Source

Specs

to_currency_codes!(atom_binary_tag(), as_options()) ::
  [atom_binary_charlist()] | no_return()

The same as to_currency_codes/2, but raises an exception if it fails.

  • options are:
    • as: :atom
    • as: :binary
    • as: :charlist

Example

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

iex> Cldr.Territory.to_currency_codes!(:US, as: :charlist)
['USD']

iex> Cldr.Territory.to_currency_codes!("PS")
[:ILS, :JOD]

iex> Cldr.Territory.to_currency_codes!("PS", as: :binary)
["ILS", "JOD"]
Link to this function

to_unicode_flag(territory_code)

View Source

Specs

to_unicode_flag(atom_binary_tag() | {:ok, atom()} | {:error, error()}) ::
  {:ok, binary()} | {:error, error()}

Unicode flag for the given territory code. Returns {:ok, flag} if successful, otherwise {:error, reason}.

Example

iex> Cldr.Territory.to_unicode_flag(:US)
{:ok, "🇺🇸"}

iex> Cldr.Territory.to_unicode_flag(:EZ)
{:error, {Cldr.UnknownFlagError, "The territory :EZ has no flag"}}
Link to this function

to_unicode_flag!(territory_code)

View Source

Specs

to_unicode_flag!(atom_binary_tag()) :: binary() | no_return()

The same as to_unicode_flag/1, but raises an exception if it fails.

Example

iex> Cldr.Territory.to_unicode_flag!(:US)
"🇺🇸"
Link to this function

translate_language_tag(from_locale, backend, options \\ [locale: Cldr.get_locale(), style: :standard])

View Source

Specs

translate_language_tag(tag(), Cldr.backend(), options()) ::
  {:ok, binary()} | {:error, error()}

Translate a LanguageTag.t into a localized string from one locale to another. Returns {:ok, result} if successful, otherwise {:error, reason}.

Example

iex> Cldr.Territory.translate_language_tag(Cldr.get_locale(), TestBackend.Cldr)
{:ok, "World"}

iex> Cldr.Territory.translate_language_tag(Cldr.get_locale(), TestBackend.Cldr, [locale: Cldr.Locale.new!("pt", TestBackend.Cldr)])
{:ok, "Mundo"}
Link to this function

translate_language_tag!(from_locale, backend, options \\ [locale: Cldr.get_locale(), style: :standard])

View Source

Specs

translate_language_tag!(tag(), Cldr.backend(), options()) ::
  binary() | no_return()

The same as translate_language_tag/2, but raises an exception if it fails.

Example

iex> Cldr.Territory.translate_language_tag!(Cldr.get_locale(), TestBackend.Cldr)
"World"

iex> Cldr.Territory.translate_language_tag!(Cldr.get_locale(), TestBackend.Cldr, [locale: Cldr.Locale.new!("pt", TestBackend.Cldr)])
"Mundo"
Link to this function

translate_territory(localized_string, from_locale, backend, to_locale \\ Cldr.get_locale())

View Source

Specs

translate_territory(binary(), binary_tag(), Cldr.backend(), binary_tag()) ::
  {:ok, binary()} | {:error, error()}

Translate a localized string from one locale to another. Returns {:ok, result} if successful, otherwise {:error, reason}.

Example

iex> Cldr.Territory.translate_territory("Reino Unido", "pt", TestBackend.Cldr)
{:ok, "UK"}

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

iex> Cldr.Territory.translate_territory("Reino Unido", :zzz, TestBackend.Cldr)
{:error, {Cldr.UnknownLocaleError, "The locale :zzz is not known."}}

iex> Cldr.Territory.translate_territory("United Kingdom", "en", TestBackend.Cldr, "zzz")
{:error, {Cldr.UnknownLocaleError, "The locale \"zzz\" is not known."}}
Link to this function

translate_territory!(localized_string, from_locale, backend, to_locale \\ Cldr.get_locale())

View Source

Specs

translate_territory!(binary(), binary_tag(), Cldr.backend(), binary_tag()) ::
  binary() | no_return()

The same as translate_territory/3, but raises an exception if it fails.

Example

iex> Cldr.Territory.translate_territory!("Reino Unido", "pt", TestBackend.Cldr)
"UK"

iex> Cldr.Territory.translate_territory!("United Kingdom", "en", TestBackend.Cldr, "pt")
"Reino Unido"