Cldr Currencies v1.0.0 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 a locale
Returns the currency metadata for the requested currency code
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
format() :: :standard | :accounting | :short | :long | :percent | :scientific
t() :: %Cldr.Currency{ cash_digits: non_neg_integer(), cash_rounding: non_neg_integer(), code: code(), count: %{}, digits: non_neg_integer(), iso_digits: non_neg_integer(), name: String.t(), narrow_symbol: String.t(), rounding: non_neg_integer(), symbol: String.t(), tender: boolean() }
Link to this section Functions
currencies_for_locale(Cldr.Locale.name() | Cldr.LanguageTag.t()) :: {:ok, Map.t()} | {:error, {Exception.t(), String.t()}}
Returns the currency metadata for a locale.
currency_for_code(code(), Cldr.LanguageTag.t()) :: {:ok, t()} | {:error, {Exception.t(), String.t()}}
Returns the currency metadata for the requested currency code.
Options
currency_code
is abinary
oratom
representation of an ISO 4217 currency code.
Examples
iex> 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> 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
}}
Returns a list of all known currency codes.
Example
iex> Cldr.Currency.known_currencies |> Enum.count
301
Returns a boolean indicating if the supplied currency code is known.
Options
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
Returns
true
orfalse
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
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.
Options
currency_code
is aString.t
or andatom
representing the new currency code to be created
Returns
{:ok, currency_code}
or{:error, {exception, message}}
Examples
iex> Cldr.Currency.make_currency_code("xzz")
{:ok, :XZZ}
iex> 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."}}
Returns a Currency
struct created from the arguments.
Options
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
Returns
{:ok, Cldr.Currency.t}
or{:error, {exception, message}}
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(:ZAA, name: "Invalid Custom Name")
{:error, {Cldr.UnknownCurrencyError, "The currency :ZAA is invalid"}}
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(: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, {Cldr.CurrencyAlreadyDefined, "Currency :XBC is already defined"}}
pluralize(pos_integer(), atom(), Keyword.t()) :: {:ok, String.t()} | {:error, {Exception.t(), String.t()}}
Returns the appropriate currency display name for the currency
, based
on the plural rules in effect for the locale
.
Options
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
Returns
{:ok, plural_string}
or{:error, {exception, message}}
Examples
iex> Cldr.Currency.pluralize 1, :USD
{:ok, "US dollar"}
iex> Cldr.Currency.pluralize 3, :USD
{:ok, "US dollars"}
iex> Cldr.Currency.pluralize 12, :USD, locale: "zh"
{:ok, "美元"}
iex> Cldr.Currency.pluralize 12, :USD, locale: "fr"
{:ok, "dollars des États-Unis"}
iex> Cldr.Currency.pluralize 1, :USD, locale: "fr"
{:ok, "dollar des États-Unis"}