Cldr Numbers v0.2.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

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
298
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 normalize_currency_code(currency_code) View Source
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
Link to this function normalize_currency_code!(currency_code) View Source

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
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"
Link to this function validate_currency_code(currency_code) View Source
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"}}