Money v4.1.0 Money.Cldr.Currency View Source

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.

Returns the currency metadata for the requested currency code.

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 locale.

Returns a list of all known currency codes.

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

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

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 the strings associated with a currency in a given locale.

Link to this section Functions

Link to this function

currencies_for_locale(locale, currency_status \\ :all) View Source
currencies_for_locale(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.Currency.currency_status()
) :: {:ok, map()} | {:error, {module(), String.t()}}
currencies_for_locale(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  Cldr.Currency.currency_status()
) :: map() | no_return()

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

Arguments

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

  • 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

MyApp.Cldr.Currency.currencies_for_locale "en" => {: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, currency_status \\ :all) View Source

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 MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

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

}

Link to this function

currency_for_code(currency_code, options \\ [locale: Money.Cldr.default_locale()]) View Source
currency_for_code(Cldr.Currency.code(), Keyword.t()) ::
  {:ok, Cldr.Currency.t()} | {:error, {module(), String.t()}}

Returns the currency metadata for the requested currency code.

Arguments

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

Examples

iex> Money.Cldr.Currency.currency_for_code("AUD")
{: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> Money.Cldr.Currency.currency_for_code("THB")
{: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_history_for_locale(language_tag) View Source
currency_history_for_locale(Cldr.LanguageTag.t() | Cldr.Locale.locale_name()) ::
  map() | {:error, {module(), String.t()}}

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

Arguments

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

Example

iex> MyApp.Cldr.Currency.currency_history_for_locale "en"
%{
  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_strings(locale, currency_status \\ :all) View Source
currency_strings(
  Cldr.LanguageTag.t() | Cldr.Locale.locale_name(),
  Cldr.Currency.currency_status()
) :: {:ok, map()} | {:error, {module(), String.t()}}

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 MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

  • 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

  • {:error, {exception, reason}}

Example

MyApp.Cldr.Currency.currency_strings "en"
=> {: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,
   ...
  }}
Link to this function

currency_strings!(locale_name, currency_status \\ :all) 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

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

  • 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

MyApp.Cldr.Currency.currency_strings! "en"
=> %{
  "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_locale(locale) View Source

Returns the current currency for a given locale.

Arguments

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

Example

iex> MyApp.Cldr.Currency.current_currency_for_locale "en"
:USD

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

known_currencies() View Source
known_currencies() :: [atom()]

Returns a list of all known currency codes.

Example

iex> Money.Cldr.Currency.known_currencies |> Enum.count
303
Link to this function

known_currency?(currency_code, custom_currencies \\ []) View Source
known_currency?(Cldr.Currency.code(), [Cldr.Currency.t()]) :: 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

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

Returns

  • true or false

Examples

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

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

iex> Money.Cldr.Currency.known_currency? :XCV
false

iex> Money.Cldr.Currency.known_currency? :XCV, [%Cldr.Currency{code: :XCV}]
true
Link to this function

make_currency_code(code) View Source
make_currency_code(binary() | atom()) :: {:ok, atom()} | {:error, binary()}

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> Money.Cldr.Currency.make_currency_code("xzz")
{:ok, :XZZ}

iex> Money.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."}}
Link to this function

new(currency, options \\ []) View Source
new(Cldr.Currency.code(), map() | Keyword.t()) ::
  {:ok, Cldr.Currency.t()} | {:error, {module(), String.t()}}

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 %Cldr.Currency{} struct

Returns

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

  • {:error, {exception, message}}

Example

iex> Money.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> Money.Cldr.Currency.new(:ZAA, name: "Invalid Custom Name")
{:error, {Cldr.UnknownCurrencyError, "The currency :ZAA is invalid"}}

iex> Money.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> Money.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> Money.Cldr.Currency.new(:XBC)
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :XBC is already defined"}}
Link to this function

pluralize(number, currency, options \\ []) View Source
pluralize(pos_integer(), atom(), 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

Returns

  • {:ok, plural_string} or

  • {:error, {exception, message}}

Examples

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

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

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

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

iex> Money.Cldr.Currency.pluralize 1, :USD, locale: "fr"
{:ok, "dollar des États-Unis"}
Link to this function

strings_for_currency(currency, locale) View Source

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 MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

Returns

  • A list of strings or

  • {:error, {exception, reason}}

Example

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