Cldr

v0.1.2

Cldr v0.1.2 Cldr.Currency

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

Summary

Types

code()
format()
t()

Functions

for_code(currency_code, locale \\ Cldr.get_locale())

Returns the currency metadata for the requested currency code

for_locale(locale)

Returns the currency metadata for a locale

known_currencies()

Returns a list of all known currency codes

known_currency?(currency_code)

Returns a boolean indicating if the supplied currency code is known

normalize_currency_code(currency_code)

Normalizes the representation of a currency code

normalize_currency_code!(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

validate_currency_code(currency_code)

Returns a normalized currency code if the code is valid or an error tuple if not

Types

code() 
code() :: String.t
format() 
format ::
  :standard |
  :accounting |
  :short |
  :long |
  :percent |
  :scientific
t() 
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}

Functions

for_code(currency_code, locale \\ Cldr.get_locale()) 
for_code(code, Cldr.locale) :: %{}

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}
for_locale(locale) 
for_locale(Cldr.locale) :: %{}

Returns the currency metadata for a locale.

known_currencies()

Returns a list of all known currency codes.

Example 

iex> Cldr.Currency.known_currencies |> Enum.count
298
known_currency?(currency_code) 
known_currency?(code) :: boolean

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

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

Examples 

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

iex> Cldr.Currency.known_currency? "GGG"
false
normalize_currency_code(currency_code) 
normalize_currency_code(binary) :: atom

Normalizes the representation of a currency code.

  • currency_code is any binary or atom 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
normalize_currency_code!(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.

  • currency_code is any binary or atom 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
validate_currency_code(currency_code) 
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 the normalized currency code if the argument is valid.

Examples 

iex> Cldr.Currency.validate_currency_code :usd
:USD

iex> Cldr.Currency.validate_currency_code "usd"
:USD

iex> Cldr.Currency.validate_currency_code "USD"
: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"}}