Cldr Numbers v0.3.2 Cldr.Currency 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 the currency metadata for the requested currency code

Returns the currency metadata for a 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

Link to this section Types

Link to this type format() View Source
format() ::
  :standard |
  :accounting |
  :short |
  :long |
  :percent |
  :scientific
Link to this type t() View Source
t() :: %Cldr.Currency{cash_digits: pos_integer(), cash_rounding: pos_integer(), code: code(), count: %{}, digits: pos_integer(), name: String.t(), narrow_symbol: String.t(), rounding: pos_integer(), symbol: String.t(), tender: boolean()}

Link to this section Functions

Link to this function for_code(currency_code, locale \\ Cldr.get_current_locale()) View Source
for_code(code(), Cldr.LanguageTag.t()) :: %{}

Returns the currency metadata for the requested currency code.

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

Examples

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

iex> Cldr.Currency.for_code("THB")
%Cldr.Currency{cash_digits: 2, cash_rounding: 0, code: "THB",
count: %{one: "Thai baht", other: "Thai baht"}, digits: 2,
name: "Thai Baht", narrow_symbol: "฿", rounding: 0, symbol: "THB",
tender: true}
Link to this function for_locale(locale \\ Cldr.get_current_locale()) View Source
for_locale(Cldr.Locale.name() | Cldr.LanguageTag.t()) :: Map.t()

Returns the currency metadata for a locale.

Returns a list of all known currency codes.

Example

iex> Cldr.Currency.known_currencies |> Enum.count
300
Link to this function known_currency?(currency_code, custom_currencies \\ []) View Source
known_currency?(code(), [Cldr.Currency, ...]) :: boolean()

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

  • 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

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

Examples

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

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

Note that since this function creates atoms, its important that this function not be called with arbitrary user input since that risks overflowing the atom table.

Link to this function new(currency, options \\ []) View Source
new(binary() | atom(), map() | list()) :: t() | {:error, binary()}

Returns a Currency struct created from the 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

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(: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, "Currency :XBC is already defined"}
Link to this function pluralize(number, currency, options \\ []) View Source

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

Examples

iex> Cldr.Currency.pluralize 1, :USD
"US dollar"

iex> Cldr.Currency.pluralize 3, :USD
"US dollars"

iex> Cldr.Currency.pluralize 12, :USD, locale: Cldr.Locale.new!("zh")
"美元"

iex> Cldr.Currency.pluralize 12, :USD, locale: Cldr.Locale.new!("fr")
"dollars des États-Unis"

iex> Cldr.Currency.pluralize 1, :USD, locale: Cldr.Locale.new!("fr")
"dollar des États-Unis"