Cldr Currencies v0.1.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

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

Link to this function currencies_for_locale(locale \\ Cldr.get_current_locale()) View Source
currencies_for_locale(Cldr.Locale.name() | Cldr.LanguageTag.t()) ::
  {:ok, Map.t()} | {:error, {Exception.t(), String.t()}}

Returns the currency metadata for a locale.

Link to this function currency_for_code(currency_code, locale \\ Cldr.get_current_locale()) View Source
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 a binary or atom 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
}}
Link to this function known_currencies() View Source
known_currencies() :: [atom()]

Returns a list of all known currency codes.

Example

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

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

Options

  • 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

Returns

  • true or false

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.

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 a String.t or and atom 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."}}
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.

Options

  • 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

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

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"}