Cldr Numbers v0.3.1 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
Normalizes the representation of a currency code
Normalizes the representation of a currency code using normalize_currency_code/1
but raises an exception if the code is known to be invalid. Note that this function
does not conclusively detect invalid currency codes and is not intended to
Returns the appropriate currency display name for the currency
, based
on the plural rules in effect for the locale
Returns a normalized currency code if the code is valid or an error tuple if not
Link to this section Types
format() :: :standard | :accounting | :short | :long | :percent | :scientific
Link to this section Functions
for_code(code(), Cldr.LanguageTag.t()) :: %{}
Returns the currency metadata for the requested currency code.
currency_code
is abinary
oratom
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}
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
known_currency?(code(), [Cldr.Currency, ...]) :: boolean()
Returns a boolean indicating if the supplied currency code is known.
currency_code
is abinary
oratom
representing an ISO4217 currency codecustom_currencies
is an optional list of custom currencies created by theCldr.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
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.
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 ISO4217options
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"}
normalize_currency_code(binary()) :: atom()
Normalizes the representation of a currency code.
currency_code
is anybinary
oratom
representation of an ISO4217 currency code.
The normalized form is an ISO4217 code in an upper case atom form.
binary
forms of currency_code
are only every converted
to an atom using String.to_existing_atom/1
. Since all known currencies
are loaded at compile time, we can detect invalid currencies in these
cases - the third example below is one such instance.
Note that normalize_currency_code
only normalizes the currency
code. For checking the validiting of a currency code, use known_currency?/1
.
Examples:
iex> Cldr.Currency.normalize_currency_code "USD"
:USD
iex> Cldr.Currency.normalize_currency_code :usd
:USD
iex> Cldr.Currency.normalize_currency_code "NADA"
{:error, {Cldr.UnknownCurrencyError, "Currency \"NADA\" is not known"}}
iex> Cldr.Currency.normalize_currency_code :ABC
:ABC
Normalizes the representation of a currency code using normalize_currency_code/1
but raises an exception if the code is known to be invalid. Note that this function
does not conclusively detect invalid currency codes and is not intended to.
currency_code
is anybinary
oratom
representation of an ISO4217 currency code.
The normalized form is an ISO4217 code in an upper case atom form.
Example:
Cldr.Currency.normalize_currency_code! "ABC"
** (Cldr.UnknownCurrencyError) Currency "ABC" is not known
(ex_cldr) lib/cldr/currency.ex:146: Cldr.Currency.normalize_currency_code!/1
Returns the appropriate currency display name for the currency
, based
on the plural rules in effect for the locale
.
number
is an integer, float orDecimal
currency
is any currency returned byCldr.Currency.known_currencies/0
options
is a keyword list of options:locale
is any locale returned byCldr.Locale.new/1
. The default isCldr.get_current_locale/0
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"
validate_currency_code(code()) :: atom()
Returns a normalized currency code if the code is valid or an error tuple if not.
Similar to the function known_currency/1
but whereas that function returns a
boolean
result, this function returns an {:ok, code}
or {:error, {exception, reason}}
tuple.
Examples
iex> Cldr.Currency.validate_currency_code :usd
{:ok, :USD}
iex> Cldr.Currency.validate_currency_code "usd"
{:ok, :USD}
iex> Cldr.Currency.validate_currency_code "USD"
{:ok, :USD}
iex> Cldr.Currency.validate_currency_code "NOPE"
{:error, {Cldr.UnknownCurrencyError, "Currency \"NOPE\" is not known"}}
iex> Cldr.Currency.validate_currency_code :ABC
{:error, {Cldr.UnknownCurrencyError, "Currency :ABC is not known"}}