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

Arguments

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

• currency_status is :all, :current, :historic, unannotated or :tender; or a list of one or more status. The default is :all. See Cldr.Currency.currency_filter/2.

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
 },
 ...
}}

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

Arguments

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

• currency_status is :all, :current, :historic, unannotated or :tender; or a list of one or more status. The default is :all. See Cldr.Currency.currency_filter/2.

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
},
...

}

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.

Returns the currency metadata for the requested currency code.

Arguments

• currency_code is a binary or atom representation of an ISO 4217 currency code.

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

• options is a Keyword list of options.

Options

• :locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

Returns the effective currency format for a given locale

Arguments

• locale a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

Returns the effective currency for a given locale

Arguments

• locale is a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

Returns the effective currency for a given locale

Arguments

• locale is any valid locale name returned by Cldr.known_locale_names/1

• backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend/0

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

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

Arguments

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

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]}
  }
}

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

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2.

• :only is :all, :current, :historic, unannotated or :tender; or a list of one or more status The default is :all. See Cldr.Currency.currency_filter/2.

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,
   ...
}}

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

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2.

• currency_status is :all, :current, :historic, unannotated or :tender; or a list of one or more status. The default is :all. See Cldr.Currency.currency_filter/2.

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,
  ...
}

Returns the current currency for a given territory.

Arguments

• territory is any valid territory name returned by Cldr.known_territories/0

Examples

iex> Cldr.Currency.current_currency_for_territory :US
:USD

iex> Cldr.Currency.current_currency_for_territory :AU
:AUD

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

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

Examples

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

iex> Cldr.Currency.current_currency_from_locale "en-AU", MyApp.Cldr
:AUD

Returns a list of all known currency codes.

Example

iex> Cldr.Currency.known_currencies |> Enum.count
303

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

Arguments

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

• custom_currencies is an optional list of custom currencies created by the Cldr.Currency.new/2 function

Returns

• true or false

Examples

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

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

iex> Cldr.Currency.known_currency? :XCV
false

iex> Cldr.Currency.known_currency? :XCV, [%Cldr.Currency{code: :XCV}]
true

Returns a valid normalized ISO4217 format custom currency code or an error.

Currency codes conform to the ISO4217 standard which means that any custom currency code must start with an "X" followed by two alphabetic characters.

Note that since this function creates atoms but to a maximum of 26 * 26 == 676 since the format permits 2 alphabetic characters only.

Arguments

• currency_code is a String.t or and atom representing the new currency code to be created

Returns

• {:ok, currency_code} or

• {:error, {exception, message}}

Examples

iex> Cldr.Currency.make_currency_code("xzz")
{:ok, :XZZ}

iex> Cldr.Currency.make_currency_code("aaa")
{:error, {Cldr.CurrencyCodeInvalid,
 "Invalid currency code \"AAA\".  Currency codes must start with 'X' followed by 2 alphabetic characters only."}}

Returns a Currency struct created from the arguments.

Arguments

• currency is a custom currency code of a format defined in ISO4217

• options is a map of options representing the optional elements of the %Currency{} struct

Returns

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

• {:error, {exception, message}}

Example

iex> Cldr.Currency.new(:XAA)
{:ok,
 %Cldr.Currency{cash_digits: 0, cash_rounding: 0, code: :XAA, count: nil,
  digits: 0, name: "", narrow_symbol: nil, rounding: 0, symbol: "",
  tender: false}}

iex> Cldr.Currency.new(:ZAA, name: "Invalid Custom Name")
{:error, {Cldr.UnknownCurrencyError, "The currency :ZAA is invalid"}}

iex> Cldr.Currency.new("xaa", name: "Custom Name")
{:ok,
 %Cldr.Currency{cash_digits: 0, cash_rounding: 0, code: :XAA, count: nil,
  digits: 0, name: "Custom Name", narrow_symbol: nil, rounding: 0, symbol: "",
  tender: false}}

iex> Cldr.Currency.new(:XAA, name: "Custom Name")
{:ok,
 %Cldr.Currency{cash_digits: 0, cash_rounding: 0, code: :XAA, count: nil,
  digits: 0, name: "Custom Name", narrow_symbol: nil, rounding: 0, symbol: "",
  tender: false}}

iex> Cldr.Currency.new(:XBC)
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :XBC is already defined"}}

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

Arguments

• number is an integer, float or Decimal

• currency is any currency returned by Cldr.Currency.known_currencies/0

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2

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

• options is a keyword list of options

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

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

Arguments

• currency is an ISO4217 currency code

• locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2.

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

Returns

• A list of strings or

• {:error, {exception, reason}}

Example

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

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

iex> Cldr.Currency.strings_for_currency :AUD, "zh", MyApp.Cldr
["澳大利亚元", "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]}
}