Cldr.Currency (Cldr Currencies v2.10.0) View Source

Defines a currency structure and a set of functions to manage the validity of a currency code and to return metadata for currencies.

Link to this section Summary

Functions

Returns a map of the metadata for all currencies for a given locale.

Returns a map of the metadata for all currencies for a given locale and raises on error.

Return only those currencies meeting the filter criteria.

Returns the currency metadata for the requested currency code.

Returns the effective currency format for a given locale

Returns the effective currency for a given locale

Returns the effective currency for a given locale

Returns a list of historic and the current currency for a given locale.

Returns a map that matches a currency string to a currency code.

Returns a map that matches a currency string to a currency code or raises an exception.

Returns the current currency for a given territory.

Returns the current currency from a given locale.

Return the display name for a currency.

Return the display name for a currency or raises and exception on error.

Returns a 2-tuple indicating if the supplied currency code is known.

Returns a boolean indicating if the supplied currency code is known.

Returns a list of all known currency codes.

Returns a Currency struct created from the arguments.

Returns the appropriate currency display name for the currency, based on the plural rules in effect for the locale.

Returns a map of private currencies.

Returns a list of all private currency codes.

Returns the strings associated with a currency in a given locale.

Returns a mapping of all ISO3166 territory codes and a list of historic and the current currency for those territories.

Determines is a new currency is already defined.

Link to this section Types

Specs

code() :: atom()

Specs

currency_status() ::
  :all | :current | :historic | :tender | :unannotated | :private

Specs

filter() :: [currency_status() | code()] | currency_status() | code()

Specs

format() :: :standard | :accounting | :short | :long | :percent | :scientific

Specs

t() :: %Cldr.Currency{
  alt_code: code(),
  cash_digits: non_neg_integer(),
  cash_rounding: non_neg_integer(),
  code: code(),
  count: %{},
  digits: non_neg_integer(),
  from: Calendar.year(),
  iso_digits: non_neg_integer(),
  name: String.t(),
  narrow_symbol: String.t(),
  rounding: non_neg_integer(),
  symbol: String.t(),
  tender: boolean(),
  to: Calendar.year()
}

Link to this section Functions

Link to this function

currencies_for_locale(locale, backend, only \\ :all, except \\ nil)

View Source

Specs

currencies_for_locale(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend(),
  only :: filter(),
  except :: filter()
) :: {:ok, map()} | {:error, {module(), String.t()}}

Returns a map of the metadata for all currencies for a given locale.

Arguments

Returns

  • {:ok, currency_map} or

  • {:error, {exception, reason}}

Example

=> Cldr.Currency.currencies_for_locale "en", MyApp.Cldr {:ok, %{

 FJD: %Cldr.Currency{
   cash_digits: 2,
   cash_rounding: 0,
   code: "FJD",
   count: %{one: "Fijian dollar", other: "Fijian dollars"},
   digits: 2,
   from: nil,
   iso_digits: 2,
   name: "Fijian Dollar",
   narrow_symbol: "$",
   rounding: 0,
   symbol: "FJD",
   tender: true,
   to: nil
 },
 SUR: %Cldr.Currency{
   cash_digits: 2,
   cash_rounding: 0,
   code: "SUR",
   count: %{one: "Soviet rouble", other: "Soviet roubles"},
   digits: 2,
   from: nil,
   iso_digits: nil,
   name: "Soviet Rouble",
   narrow_symbol: nil,
   rounding: 0,
   symbol: "SUR",
   tender: true,
   to: nil
 },
 ...
}}
Link to this function

currencies_for_locale!(locale, backend, only \\ :all, except \\ nil)

View Source

Specs

currencies_for_locale!(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.backend(),
  only :: filter(),
  except :: filter()
) :: map() | no_return()

Returns a map of the metadata for all currencies for a given locale and raises on error.

Arguments

Returns

  • {:ok, currency_map} or

  • raises an exception

Example

#=> MyApp.Cldr.Currency.currencies_for_locale! "en" %{

FJD: %Cldr.Currency{
  cash_digits: 2,
  cash_rounding: 0,
  code: "FJD",
  count: %{one: "Fijian dollar", other: "Fijian dollars"},
  digits: 2,
  from: nil,
  iso_digits: 2,
  name: "Fijian Dollar",
  narrow_symbol: "$",
  rounding: 0,
  symbol: "FJD",
  tender: true,
  to: nil
},
SUR: %Cldr.Currency{
  cash_digits: 2,
  cash_rounding: 0,
  code: "SUR",
  count: %{one: "Soviet rouble", other: "Soviet roubles"},
  digits: 2,
  from: nil,
  iso_digits: nil,
  name: "Soviet Rouble",
  narrow_symbol: nil,
  rounding: 0,
  symbol: "SUR",
  tender: true,
  to: nil
},
...

}

Link to this function

currency_filter(currencies, only \\ :all, except \\ nil)

View Source

Return only those currencies meeting the filter criteria.

Arguments

  • currency is a Cldr.Currency.t, a list of Cldr.Currency.t or a map where the values of each item is a Cldr.Currency.t

  • only is :all, :current, :historic, :tender unannotated or a list of one or more status or currency codes. The default is :all

  • except is :current, :historic, :tender unannotated or a list of one or more status or currency codes. The default is nil

Currency Status

A currency may be in current use, of historic interest only. It may or may not be legal tender. And it may mostly be used as a financial instrument. To help return the most useful currencies the currency status code acts as follows:

  • :all, the default, returns all currencies

  • :current returns those currencies that have a :to date of nil and which also is a known ISO4217 currency

  • :historic is the opposite of :current

  • :tender is a currency that is legal tender

  • :unannotated is a currency that doesn't have "(some string)" in its name. These are usually financial instruments.

Link to this function

currency_for_code(currency_or_currency_code, backend, options \\ [])

View Source

Specs

currency_for_code(code() | t(), Cldr.backend(), Keyword.t()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Returns the currency metadata for the requested currency code.

Arguments

  • currency_or_currency_code is a binary or atom representation of an ISO 4217 currency code, or a %Cldr.Currency{} struct.

  • backend is any module that includes use Cldr and therefore is a Cldr backend module

  • options is a Keyword list of options.

Options

Examples

iex> Cldr.Currency.currency_for_code("AUD", MyApp.Cldr)
{:ok,
  %Cldr.Currency{
    cash_digits: 2,
    cash_rounding: 0,
    code: "AUD",
    count: %{one: "Australian dollar", other: "Australian dollars"},
    digits: 2,
    iso_digits: 2,
    name: "Australian Dollar",
    narrow_symbol: "$",
    rounding: 0,
    symbol: "A$",
    tender: true
}}

iex> Cldr.Currency.currency_for_code("THB", MyApp.Cldr)
{:ok,
  %Cldr.Currency{
    cash_digits: 2,
    cash_rounding: 0,
    code: "THB",
    count: %{one: "Thai baht", other: "Thai baht"},
    digits: 2,
    iso_digits: 2,
    name: "Thai Baht",
    narrow_symbol: "฿",
    rounding: 0,
    symbol: "THB",
    tender: true
}}
Link to this function

currency_format_from_locale(language_tag)

View Source

Returns the effective currency format for a given locale

Arguments

Returns

  • Either :accounting or :currency

Examples

iex> {:ok, locale} = Cldr.validate_locale "en", MyApp.Cldr
iex> Cldr.Currency.currency_format_from_locale locale
:currency

iex> {:ok, locale} = Cldr.validate_locale "en-AU-u-cu-eur", MyApp.Cldr
iex> Cldr.Currency.currency_format_from_locale locale
:currency

iex> {:ok, locale} = Cldr.validate_locale "en-AU-u-cu-eur-cf-account", MyApp.Cldr
iex> Cldr.Currency.currency_format_from_locale locale
:accounting
Link to this function

currency_from_locale(locale)

View Source

Returns the effective currency for a given locale

Arguments

Returns

  • A ISO 4217 currency code as an upcased atom

Examples

iex> {:ok, locale} = Cldr.validate_locale "en", MyApp.Cldr
iex> Cldr.Currency.currency_from_locale locale
:USD

iex> {:ok, locale} = Cldr.validate_locale "en-AU", MyApp.Cldr
iex> Cldr.Currency.currency_from_locale locale
:AUD

iex> Cldr.Currency.currency_from_locale "en-GB"
:GBP
Link to this function

currency_from_locale(locale, backend \\ default_backend())

View Source

Returns the effective currency for a given locale

Arguments

Returns

  • A ISO 4217 currency code as an upcased atom

Examples

iex> Cldr.Currency.currency_from_locale "fr-CH", MyApp.Cldr
:CHF

iex> Cldr.Currency.currency_from_locale "fr-CH-u-cu-INR", MyApp.Cldr
:INR
Link to this function

currency_history_for_locale(locale)

View Source

Specs

currency_history_for_locale(Cldr.LanguageTag.t()) ::
  {:ok, map()} | {:error, {atom(), binary()}}

Returns a list of historic and the current currency for a given locale.

Arguments

Example

iex> Cldr.Currency.currency_history_for_locale "en", MyApp.Cldr
{:ok,
  %{
    USD: %{from: ~D[1792-01-01], to: nil},
    USN: %{tender: false},
    USS: %{from: nil, tender: false, to: ~D[2014-03-01]}
  }
}
Link to this function

currency_history_for_locale(locale_name, backend)

View Source

Specs

currency_history_for_locale(Cldr.Locale.locale_name(), Cldr.backend()) ::
  {:ok, map()} | {:error, {module(), String.t()}}
Link to this function

currency_strings(locale, backend, only \\ :all, except \\ nil)

View Source

Returns a map that matches a currency string to a currency code.

A currency string is a localised name or symbol representing a currency in a locale-specific manner.

Arguments

Returns

  • {:ok, currency_string_map} or

  • {:error, {exception, reason}}

Example

=> Cldr.Currency.currency_strings "en", MyApp.Cldr
{:ok,
 %{
   "mexican silver pesos" => :MXP,
   "sudanese dinar" => :SDD,
   "bad" => :BAD,
   "rsd" => :RSD,
   "swazi lilangeni" => :SZL,
   "zairean new zaire" => :ZRN,
   "guyanaese dollars" => :GYD,
   "equatorial guinean ekwele" => :GQE,
   ...
}}

# Currencies match all currency status'
=> Cldr.Currency.currency_strings "en", MyApp.Cldr, [:tender, :current, :unannotated]
{:ok,
 %{
   "rsd" => :RSD,
   "swazi lilangeni" => :SZL,
   "guyanaese dollars" => :GYD,
   "syrian pound" => :SYP,
   "scr" => :SCR,
   "bangladeshi takas" => :BDT,
   "netherlands antillean guilders" => :ANG,
   "pen" => :PEN,
   ...
}}
Link to this function

currency_strings!(locale, backend, only \\ :all, except \\ nil)

View Source

Returns a map that matches a currency string to a currency code or raises an exception.

A currency string is a localised name or symbol representing a currency in a locale-specific manner.

Arguments

Returns

  • {:ok, currency_string_map} or

  • raises an exception

Example

=> Cldr.Currency.currency_strings! "en", MyApp.Cldr
%{
  "mexican silver pesos" => :MXP,
  "sudanese dinar" => :SDD,
  "bad" => :BAD,
  "rsd" => :RSD,
  "swazi lilangeni" => :SZL,
  "zairean new zaire" => :ZRN,
  "guyanaese dollars" => :GYD,
  "equatorial guinean ekwele" => :GQE,
  ...
}
Link to this function

current_currency_for_territory(territory)

View Source

Specs

current_currency_for_territory(Cldr.territory()) ::
  code() | nil | {:error, {module(), String.t()}}

Returns the current currency for a given territory.

Arguments

Examples

iex> Cldr.Currency.current_currency_for_territory :US
:USD

iex> Cldr.Currency.current_currency_for_territory :AU
:AUD
Link to this function

current_currency_from_locale(locale)

View Source

Specs

current_currency_from_locale(Cldr.LanguageTag.t()) :: any()

Returns the current currency from a given locale.

This function does not consider the U extenion parameters cu or rg. It is recommended to us Cldr.Currency.currency_from_locale/1 in most circumstances.

Arguments

Examples

iex> Cldr.Currency.current_currency_from_locale "en", MyApp.Cldr
:USD

iex> Cldr.Currency.current_currency_from_locale "en-AU", MyApp.Cldr
:AUD
Link to this function

current_currency_from_locale(locale_name, backend)

View Source

Specs

current_currency_from_locale(Cldr.Locale.locale_name(), Cldr.backend()) ::
  code() | nil | {:error, {module(), String.t()}}
Link to this function

display_name(currency, options \\ [])

View Source

Specs

display_name(t() | code(), Keyword.t()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Return the display name for a currency.

The display name is useful for UI uses, for example in menus. The display name is typically capitalized for stand-alone use where as the display name returned by Cldr.Currency.pluralize/4 is typically lower-cased for use within sentences.

Arguments

Options

Returns

  • {:ok, display_name}

  • or {:error, {exception, reason}}

Examples

iex> Cldr.Currency.display_name :AUD, backend: MyApp.Cldr
{:ok, "Australian Dollar"}

iex> Cldr.Currency.display_name "AUD", backend: MyApp.Cldr, locale: "fr"
{:ok, "dollar australien"}

iex> Cldr.Currency.display_name "EUR", backend: MyApp.Cldr, locale: "de"
{:ok, "Euro"}

iex> Cldr.Currency.display_name "ZZZ", backend: MyApp.Cldr
{:error, {Cldr.UnknownCurrencyError, "The currency \"ZZZ\" is invalid"}}
Link to this function

display_name!(currency, options \\ [])

View Source

Specs

display_name!(t() | code(), Keyword.t()) :: String.t() | no_return()

Return the display name for a currency or raises and exception on error.

The display name is useful for UI uses, for example in menus. The display name is typically capitalized for stand-alone use where as the display name returned by Cldr.Currency.pluralize/4 is typically lower-cased for use within sentences.

Arguments

Options

Returns

  • display_name

  • or raises an exception

Examples

iex> Cldr.Currency.display_name! :AUD, backend: MyApp.Cldr
"Australian Dollar"

iex> Cldr.Currency.display_name! "AUD", backend: MyApp.Cldr, locale: "fr"
"dollar australien"

iex> Cldr.Currency.display_name! "EUR", backend: MyApp.Cldr, locale: "de"
"Euro"

#=> Cldr.Currency.display_name! "ZZZ", backend: MyApp.Cldr
** (Cldr.UnknownCurrencyError) The currency "ZZZ" is invalid
Link to this function

expand_filter(currencies, arg2, filter_list)

View Source
This function is deprecated. Use known_currency_codes/0.

See Cldr.Currency.known_currency_codes/0.

Link to this function

known_currency?(currency)

View Source
This function is deprecated. Use known_currency_code?/0.

See Cldr.Currency.known_currency_code?/1.

Link to this function

known_currency_code(currency_code)

View Source

Specs

known_currency_code(code()) :: {:ok, code()} | {:error, {module(), String.t()}}

Returns a 2-tuple indicating if the supplied currency code is known.

Arguments

  • currency_code is a binary or atom representing an ISO4217 currency code

Returns

  • {:ok, currency_code} or

  • {:error, {exception, reason}}

Examples

iex> Cldr.Currency.known_currency_code "AUD"
{:ok, :AUD}

iex> Cldr.Currency.known_currency_code "GGG"
{:error, {Cldr.UnknownCurrencyError, "The currency \"GGG\" is invalid"}}
Link to this function

known_currency_code?(currency_code)

View Source

Specs

known_currency_code?(code()) :: boolean()

Returns a boolean indicating if the supplied currency code is known.

Arguments

  • currency_code is a binary or atom representing an ISO4217 currency code

Returns

  • true or false

Examples

iex> Cldr.Currency.known_currency_code? "AUD"
true

iex> Cldr.Currency.known_currency_code? "GGG"
false

iex> Cldr.Currency.known_currency_code? :XCV
false

Specs

known_currency_codes() :: [atom()]

Returns a list of all known currency codes.

Example

iex> Cldr.Currency.known_currency_codes
Link to this function

new(currency, options \\ [])

View Source

Specs

new(binary() | atom(), map() | list()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Returns a Currency struct created from the arguments.

Arguments

  • currency is a private use currency code in a format defined by ISO4217 which is X followed by two alphanumeric characters.

  • options is a map of options representing the optional elements of the Cldr.Currency.t struct.

Options

  • :name is the name of the currenct. Required.
  • :digits is the precision of the currency. Required.
  • :symbol is the currency symbol. Optional.
  • :narrow_symbol is an alternative narrow symbol. Optional.
  • :round_nearest is the rounding precision such as 0.05. Optional.
  • :alt_code is an alternative currency code for application use.
  • :cash_digits is the precision of the currency when used as cash. Optional.
  • :cash_round_nearest is the rounding precision when used as cash such as 0.05. Optional.

Returns

  • {:ok, Cldr.Currency.t} or

  • {:error, {exception, message}}

Example

iex> Cldr.Currency.new(:XAC, name: "XAC currency", digits: 0)
{:ok,
 %Cldr.Currency{
   alt_code: :XAC,
   cash_digits: 0,
   cash_rounding: nil,
   code: :XAC,
   count: %{other: "XAC currency"},
   digits: 0,
   from: nil,
   iso_digits: 0,
   name: "XAC currency",
   narrow_symbol: nil,
   rounding: 0,
   symbol: "XAC",
   tender: false,
   to: nil
 }}
iex> Cldr.Currency.new(:XBC)
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :XBC is already defined."}}
iex> MyApp.Cldr.Currency.new(:XAB, name: "Private Use Name")
{:error, "Required options are missing. Required options are [:name, :digits]"}
iex> Cldr.Currency.new(:ZAA, name: "Invalid Private Use Name", digits: 0)
{:error, {Cldr.UnknownCurrencyError, "The currency :ZAA is invalid"}}
Link to this function

pluralize(number, currency, backend, options \\ [])

View Source

Specs

pluralize(pos_integer(), code(), Cldr.backend(), Keyword.t()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns the appropriate currency display name for the currency, based on the plural rules in effect for the locale.

Arguments

Options

  • :locale is any locale returned by Cldr.Locale.new!/2. The default is <backend>.get_locale/1

Returns

  • {:ok, plural_string} or

  • {:error, {exception, message}}

Examples

iex> Cldr.Currency.pluralize 1, :USD, MyApp.Cldr
{:ok, "US dollar"}

iex> Cldr.Currency.pluralize 3, :USD, MyApp.Cldr
{:ok, "US dollars"}

iex> Cldr.Currency.pluralize 12, :USD, MyApp.Cldr, locale: "zh"
{:ok, "美元"}

iex> Cldr.Currency.pluralize 12, :USD, MyApp.Cldr, locale: "fr"
{:ok, "dollars des États-Unis"}

iex> Cldr.Currency.pluralize 1, :USD, MyApp.Cldr, locale: "fr"
{:ok, "dollar des États-Unis"}

Specs

private_currencies() :: %{required(code()) => t()}

Returns a map of private currencies.

These comprise all currencies created with Cldr.Currency.new/2.

Link to this function

private_currency_codes()

View Source

Specs

private_currency_codes() :: [atom()]

Returns a list of all private currency codes.

Link to this function

strings_for_currency(currency, locale, backend)

View Source

Returns the strings associated with a currency in a given locale.

Arguments

Returns

  • A list of strings or

  • {:error, {exception, reason}}

Example

iex> Cldr.Currency.strings_for_currency(:AUD, "en", MyApp.Cldr) |> Enum.sort
["a$", "aud", "australian dollar", "australian dollars"]

iex> Cldr.Currency.strings_for_currency(:AUD, "de", MyApp.Cldr) |> Enum.sort
["au$", "aud", "australische dollar", "australischer dollar"]

iex> Cldr.Currency.strings_for_currency(:AUD, "zh", MyApp.Cldr) |> Enum.sort
["au$", "aud", "澳大利亚元"]

Returns a mapping of all ISO3166 territory codes and a list of historic and the current currency for those territories.

Example

iex> Cldr.Currency.territory_currencies |> Map.get(:LT)
%{
  EUR: %{from: ~D[2015-01-01], to: nil},
  LTL: %{from: nil, to: ~D[2014-12-31]},
  LTT: %{from: nil, to: ~D[1993-06-25]},
  SUR: %{from: nil, to: ~D[1992-10-01]}
}
Link to this function

territory_currencies(territory)

View Source
Link to this function

territory_currencies!(territory)

View Source
Link to this function

validate_new_currency(code)

View Source

Specs

validate_new_currency(code()) ::
  {:ok, code()} | {:error, {module(), String.t()}}

Determines is a new currency is already defined.

Example

iex> Cldr.Currency.validate_new_currency :XAD
{:ok, :XAD}

iex> Cldr.Currency.validate_new_currency :USD
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :USD is already defined."}}