# `Cldr.Currency` [🔗](https://github.com/elixir-cldr/cldr_currencies/blob/v2.17.1/lib/cldr/currency.ex#L1) Defines a currency structure and a set of functions to manage the validity of a currency code and to return metadata for currencies. # `currency_code` ```elixir @type currency_code() :: atom() ``` # `currency_reference` ```elixir @type currency_reference() :: currency_code() | binary() ``` # `currency_status` ```elixir @type currency_status() :: :all | :current | :historic | :tender | :unannotated | :private ``` # `filter` ```elixir @type filter() :: [currency_status() | currency_code()] | currency_status() | currency_code() ``` # `format` ```elixir @type format() :: :standard | :accounting | :short | :long | :percent | :scientific ``` # `t` ```elixir @type t() :: %Cldr.Currency{ alt_code: currency_code(), cash_digits: non_neg_integer(), cash_rounding: non_neg_integer(), code: currency_code(), count: %{}, decimal_separator: String.t() | nil, digits: non_neg_integer(), from: Calendar.year(), grouping_separator: String.t() | nil, iso_digits: non_neg_integer(), name: String.t(), narrow_symbol: String.t(), rounding: non_neg_integer(), symbol: String.t(), tender: boolean(), to: Calendar.year() } ``` # `territory` ```elixir @type territory() :: atom() | String.t() ``` # `annotated?` ```elixir @spec annotated?(currency :: t()) :: boolean() ``` Returns a boolean indicating if a given currency is annotated. Annotated means that the currency description has annotations (comments inside parenthesis). This is mostly found in currency codes used as financial instruments (not legal tender). ### Arguments * `currency` is a `t:Cldr.Currency.t/0` ### Returns * `true` or `false` # `currencies_for_locale` ```elixir @spec currencies_for_locale( Cldr.Locale.locale_name() | Cldr.LanguageTag.t(), Cldr.backend(), only :: filter(), except :: filter() ) :: {:ok, map()} | {:error, {module(), String.t()}} ``` Returns a map of the metadata for all currencies for a given locale. ### Arguments * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2` * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module * `currency_status` is `:all`, `:current`, `:historic`, `unannotated` or `:tender`; or a list of one or more status. The default is `:all`. See `Cldr.Currency.currency_filter/2`. ### Returns * `{:ok, currency_map}` or * `{:error, {exception, reason}}` ### Example => Cldr.Currency.currencies_for_locale("en", MyApp.Cldr) {:ok, %{ FJD: %Cldr.Currency{ cash_digits: 2, cash_rounding: 0, code: "FJD", count: %{one: "Fijian dollar", other: "Fijian dollars"}, digits: 2, from: nil, iso_digits: 2, name: "Fijian Dollar", narrow_symbol: "$", rounding: 0, symbol: "FJD", tender: true, to: nil }, SUR: %Cldr.Currency{ cash_digits: 2, cash_rounding: 0, code: "SUR", count: %{one: "Soviet rouble", other: "Soviet roubles"}, digits: 2, from: nil, iso_digits: nil, name: "Soviet Rouble", narrow_symbol: nil, rounding: 0, symbol: "SUR", tender: true, to: nil }, ... }} # `currencies_for_locale!` ```elixir @spec currencies_for_locale!( Cldr.Locale.locale_name() | Cldr.LanguageTag.t(), Cldr.backend(), only :: filter(), except :: filter() ) :: map() | no_return() ``` Returns a map of the metadata for all currencies for a given locale and raises on error. ### Arguments * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2` * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module * `currency_status` is `:all`, `:current`, `:historic`, `unannotated` or `:tender`; or a list of one or more status. The default is `:all`. See `Cldr.Currency.currency_filter/2`. ### Returns * `{:ok, currency_map}` or * raises an exception ### Example #=> MyApp.Cldr.Currency.currencies_for_locale!("en") %{ FJD: %Cldr.Currency{ cash_digits: 2, cash_rounding: 0, code: "FJD", count: %{one: "Fijian dollar", other: "Fijian dollars"}, digits: 2, from: nil, iso_digits: 2, name: "Fijian Dollar", narrow_symbol: "$", rounding: 0, symbol: "FJD", tender: true, to: nil }, SUR: %Cldr.Currency{ cash_digits: 2, cash_rounding: 0, code: "SUR", count: %{one: "Soviet rouble", other: "Soviet roubles"}, digits: 2, from: nil, iso_digits: nil, name: "Soviet Rouble", narrow_symbol: nil, rounding: 0, symbol: "SUR", tender: true, to: nil }, ... } # `currency_filter` Return only those currencies meeting the filter criteria. ### Arguments * `currency` is a `t:Cldr.Currency.t/0`, a list of `t:Cldr.Currency.t/0` or a map where the values of each item is a `Cldr.Currency.t` * `only` is `:all`, `:current`, `:historic`, `:tender` `unannotated` or a list of one or more status or currency codes. The default is `:all` * `except` is `:current`, `:historic`, `:tender` `unannotated` or a list of one or more status or currency codes. The default is `nil` ## Currency Status A currency may be in current use or of historic interest only. It may or may not be legal tender. And it may mostly be used as a financial instrument. To help return the most useful currencies the currency status code acts as follows: * `:all`, the default, returns all currencies * `:current` returns those currencies that have a `:to` date of nil and which also is a known ISO4217 currency * `:historic` is the opposite of `:current` * `:tender` is a currency that is legal tender * `:unannotated` is a currency that doesn't have "(some string)" in its name. These are usually financial instruments. # `currency_for_code` ```elixir @spec currency_for_code(currency_reference() | t(), Cldr.backend(), Keyword.t()) :: {:ok, t()} | {:error, {module(), String.t()}} ``` Returns the currency metadata for the requested currency code. ### Arguments * `currency_or_currency_code` is a `binary` or `atom` representation of an ISO 4217 currency code, or a `t:Cldr.Currency.t/0` struct. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. The default is `Cldr.default_backend!/0`. * `options` is a `Keyword` list of options. The default is `[]`. ### Options * `:locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2` ### Returns * A `{:ok, currency}` or * `{:error, {exception, reason}}` ### Examples iex> Cldr.Currency.currency_for_code(:AUD, MyApp.Cldr) {: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", MyApp.Cldr) {: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 }} # `currency_for_code!` *since 2.14.0* ```elixir @spec currency_for_code!(currency_code() | t(), Cldr.backend(), Keyword.t()) :: t() | no_return() ``` Returns the currency metadata for the requested currency code. ### Arguments * `currency_or_currency_code` is a `binary` or `atom` representation of an ISO 4217 currency code, or a `t:Cldr.Currency.t/0` struct. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module * `options` is a `Keyword` list of options. ### Options * `:locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2` ### Returns * A `t:Cldr.Current.t/0` or * raises an exception ### Examples iex> Cldr.Currency.currency_for_code!("AUD", MyApp.Cldr) %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", MyApp.Cldr) %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 } # `currency_format_from_locale` Returns the effective currency format for a given locale. ### Arguments * `locale` a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. ### Returns * Either `:accounting` or `:currency`. ### Examples iex> {:ok, locale} = Cldr.validate_locale("en", MyApp.Cldr) iex> Cldr.Currency.currency_format_from_locale locale :currency iex> {:ok, locale} = Cldr.validate_locale("en-AU-u-cu-eur", MyApp.Cldr) iex> Cldr.Currency.currency_format_from_locale locale :currency iex> {:ok, locale} = Cldr.validate_locale("en-AU-u-cu-eur-cf-account", MyApp.Cldr) iex> Cldr.Currency.currency_format_from_locale locale :accounting # `currency_format_from_locale` Returns the effective currency format for a given locale. ### Arguments * `locale` a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. The default is `Cldr.default_backend!/0`. ### Returns * Either `:accounting` or `:currency`. ### Examples iex> Cldr.Currency.currency_format_from_locale("en", MyApp.Cldr) :currency iex> Cldr.Currency.currency_format_from_locale("en-AU-u-cu-eur", MyApp.Cldr) :currency iex> Cldr.Currency.currency_format_from_locale("en-AU-u-cu-eur-cf-account", MyApp.Cldr) :accounting # `currency_from_locale` Returns the effective currency for a given locale. ### Arguments * `locale` is a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. ### Returns * A ISO 4217 currency code as an upcased atom. ### Examples iex> {:ok, locale} = Cldr.validate_locale("en", MyApp.Cldr) iex> Cldr.Currency.currency_from_locale locale :USD iex> {:ok, locale} = Cldr.validate_locale("en-AU", MyApp.Cldr) iex> Cldr.Currency.currency_from_locale locale :AUD iex> Cldr.Currency.currency_from_locale("en-GB") :GBP # `currency_from_locale` Returns the effective currency for a given locale. ### Arguments * `locale` is any valid locale name returned by `Cldr.known_locale_names/1`. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. The default is `Cldr.default_backend!/0`. ### Returns * A ISO 4217 currency code as an upcased atom. ### Examples iex> Cldr.Currency.currency_from_locale("fr-CH", MyApp.Cldr) :CHF iex> Cldr.Currency.currency_from_locale("fr-CH-u-cu-INR", MyApp.Cldr) :INR # `currency_history_for_locale` ```elixir @spec currency_history_for_locale(Cldr.LanguageTag.t()) :: {:ok, %{required(currency :: currency_code()) => map()}} | {:error, {module(), String.t()}} ``` Returns a list of historic and the current currency for a given locale. ### Arguments * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. ### Example iex> Cldr.Currency.currency_history_for_locale("en", MyApp.Cldr) {:ok, %{ USD: %{from: ~D[1792-01-01], to: nil}, USN: %{tender: false}, USS: %{from: nil, tender: false, to: ~D[2014-03-01]} } } # `currency_history_for_locale` ```elixir @spec currency_history_for_locale(Cldr.Locale.locale_reference(), Cldr.backend()) :: {:ok, map()} | {:error, {module(), String.t()}} ``` # `currency_strings` Returns a map that matches a currency string to a currency code. A currency string is a localised name or symbol representing a currency in a locale-specific manner. ### Arguments * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. * `:only` is `:all`, `:current`, `:historic`, `unannotated` or `:tender`; or a list of one or more status The default is `:all`. See `Cldr.Currency.currency_filter/2`. ### Returns * `{:ok, currency_string_map}` or * `{:error, {exception, reason}}` ### Example => Cldr.Currency.currency_strings("en", MyApp.Cldr) {:ok, %{ "mexican silver pesos" => :MXP, "sudanese dinar" => :SDD, "bad" => :BAD, "rsd" => :RSD, "swazi lilangeni" => :SZL, "zairean new zaire" => :ZRN, "guyanaese dollars" => :GYD, "equatorial guinean ekwele" => :GQE, ... }} # Currencies match all currency status' => Cldr.Currency.currency_strings "en", MyApp.Cldr, [:tender, :current, :unannotated] {:ok, %{ "rsd" => :RSD, "swazi lilangeni" => :SZL, "guyanaese dollars" => :GYD, "syrian pound" => :SYP, "scr" => :SCR, "bangladeshi takas" => :BDT, "netherlands antillean guilders" => :ANG, "pen" => :PEN, ... }} # `currency_strings!` Returns a map that matches a currency string to a currency code or raises an exception. A currency string is a localised name or symbol representing a currency in a locale-specific manner. ### Arguments * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. * `currency_status` is `:all`, `:current`, `:historic`, `unannotated` or `:tender`; or a list of one or more status. The default is `:all`. See `Cldr.Currency.currency_filter/2`. ### Returns * `{:ok, currency_string_map}` or * raises an exception. ### Example => Cldr.Currency.currency_strings!("en", MyApp.Cldr) %{ "mexican silver pesos" => :MXP, "sudanese dinar" => :SDD, "bad" => :BAD, "rsd" => :RSD, "swazi lilangeni" => :SZL, "zairean new zaire" => :ZRN, "guyanaese dollars" => :GYD, "equatorial guinean ekwele" => :GQE, ... } # `current?` ```elixir @spec current?(currency :: t()) :: boolean() ``` Returns a boolean indicating if a given currency is current. Current means that the currency is in current use. ### Arguments * `currency` is a `t:Cldr.Currency.t/0` ### Returns * `true` or `false` # `current_currency_for_territory` ```elixir @spec current_currency_for_territory(Cldr.Locale.territory_code()) :: currency_code() | nil | {:error, {module(), String.t()}} ``` Returns the current currency for a given territory. ### Arguments * `territory` is any valid territory name returned by `Cldr.known_territories/0` ### Examples iex> Cldr.Currency.current_currency_for_territory(:US) :USD iex> Cldr.Currency.current_currency_for_territory(:AU) :AUD # `current_currency_from_locale` ```elixir @spec current_currency_from_locale(Cldr.LanguageTag.t()) :: currency_code() | {:error, {module(), String.t()}} ``` Returns the current currency from a given locale. This function does not consider the `U` extenion parameters `cu` or `rg`. It is recommended to us `Cldr.Currency.currency_from_locale/1` in most circumstances. ### Arguments * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. ### Examples iex> Cldr.Currency.current_currency_from_locale("en", MyApp.Cldr) :USD iex> Cldr.Currency.current_currency_from_locale("en-AU", MyApp.Cldr) :AUD # `current_currency_from_locale` ```elixir @spec current_currency_from_locale( Cldr.Locale.locale_name() | String.t(), Cldr.backend() ) :: currency_code() | nil | {:error, {module(), String.t()}} ``` # `current_territory_currencies` *since 2.15.0* ```elixir @spec current_territory_currencies() :: %{ required(Cldr.Locale.territory_code()) => currency_code() } ``` Returns a mapping from a territory code to its current currency code. If a territory has no current currency (like Antartica, territory code `:AQ`) then no mapping is returned for that territory. ### Returns * A map of `{territory_code => currency.code}` # `display_name` ```elixir @spec display_name(t() | currency_code(), Keyword.t()) :: {:ok, String.t()} | {:error, {module(), String.t()}} ``` Return the display name for a currency. The display name is useful for UI uses, for example in menus. The display name is typically capitalized for stand-alone use where as the display name returned by `Cldr.Currency.pluralize/4` is typically lower-cased for use within sentences. ### Arguments * `currency` is any currency code returned by `Cldr.Currency.known_currencies/0` or a `t:Cldr.Currency.t/0` struct returned by `Cldr.Currency.currency_for_code/3`. ### Options * `:locale` is any locale returned by `Cldr.Locale.new!/2`. The default is `Cldr.get_locale/0`. * `:backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. The default is `Cldr.default_backend!/0`. ### Returns * `{:ok, display_name}` * or `{:error, {exception, reason}}` ### Examples iex> Cldr.Currency.display_name :AUD, backend: MyApp.Cldr {:ok, "Australian Dollar"} iex> Cldr.Currency.display_name "AUD", backend: MyApp.Cldr, locale: "fr" {:ok, "dollar australien"} iex> Cldr.Currency.display_name "EUR", backend: MyApp.Cldr, locale: "de" {:ok, "Euro"} iex> Cldr.Currency.display_name(:XCG, locale: :aa) {:error, {Cldr.CurencyNoDisplayName, "The currency \"XCG\" has no display name in locale :aa"}} iex> Cldr.Currency.display_name "ZZZ", backend: MyApp.Cldr {:error, {Cldr.UnknownCurrencyError, "The currency \"ZZZ\" is unknown"}} # `display_name!` ```elixir @spec display_name!(t() | currency_code(), Keyword.t()) :: String.t() | no_return() ``` Return the display name for a currency or raises and exception on error. The display name is useful for UI uses, for example in menus. The display name is typically capitalized for stand-alone use where as the display name returned by `Cldr.Currency.pluralize/4` is typically lower-cased for use within sentences. ### Arguments * `currency` is any currency code returned by `Cldr.Currency.known_currencies/0` or a `t:Cldr.Currency.t/0` struct returned by `Cldr.Currency.currency_for_code/3`. ### Options * `:locale` is any locale returned by `Cldr.Locale.new!/2`. The default is `Cldr.get_locale/0`. * `:backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. The default is `Cldr.default_backend!/0`. ### Returns * `display_name` * or raises an exception ### Examples iex> Cldr.Currency.display_name! :AUD, backend: MyApp.Cldr "Australian Dollar" iex> Cldr.Currency.display_name! "AUD", backend: MyApp.Cldr, locale: "fr" "dollar australien" iex> Cldr.Currency.display_name! "EUR", backend: MyApp.Cldr, locale: "de" "Euro" #=> Cldr.Currency.display_name! "ZZZ", backend: MyApp.Cldr ** (Cldr.UnknownCurrencyError) The currency "ZZZ" is invalid # `historic?` ```elixir @spec historic?(currency :: t()) :: boolean() ``` Returns a boolean indicating if a given currency is historic. Historic means that the currency is no longer in use. ### Arguments * `currency` is a `t:Cldr.Currency.t/0` ### Returns * `true` or `false` # `known_currencies` > This function is deprecated. Use known_currency_codes/0. # `known_currency?` > This function is deprecated. Use known_currency_code?/0. # `known_currency_code` ```elixir @spec known_currency_code(currency_code()) :: {:ok, currency_code()} | {:error, {module(), String.t()}} ``` Returns a 2-tuple indicating if the supplied currency code is known. ### Arguments * `currency_code` is a `binary` or `atom` representing an ISO4217 currency code. ### Returns * `{:ok, currency_code}` or * `{:error, {exception, reason}}` ### Examples iex> Cldr.Currency.known_currency_code("AUD") {:ok, :AUD} iex> Cldr.Currency.known_currency_code("GGG") {:error, {Cldr.UnknownCurrencyError, "The currency \"GGG\" is unknown"}} # `known_currency_code?` ```elixir @spec known_currency_code?(currency_code()) :: boolean() ``` Returns a boolean indicating if the supplied currency code is known. ### Arguments * `currency_code` is a `binary` or `atom` representing an ISO4217 currency code. ### Returns * `true` or `false` ### Examples iex> Cldr.Currency.known_currency_code?("AUD") true iex> Cldr.Currency.known_currency_code?("GGG") false iex> Cldr.Currency.known_currency_code?(:XCV) false # `known_currency_codes` ```elixir @spec known_currency_codes() :: [currency_code(), ...] ``` Returns a list of all known currency codes. ### Example iex> Cldr.Currency.known_currency_codes() # `new` ```elixir @spec new(binary() | atom(), map() | list()) :: {:ok, t()} | {:error, {module(), String.t()}} ``` Returns a `t:Cldr.Currency.t/0` struct created from the arguments. ### Arguments * `currency` is a private use currency code in a format defined by [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) which is `X` followed by two alphanumeric characters OR a custom currency code that at least four and less than 11 characters starting with a character in the range `[a-zA-Z]` followed by three or more characters in the range `[a-zA-Z0-9]`. The use of four characters or more makes it easy to differentiate between ISO4217 currency codes and custom currency codes. * `options` is a map of options representing the optional elements of the `t:Cldr.Currency.t/0` struct. ### Options * `:name` is the name of the currency. Required. * `:digits` is the precision of the currency. Required. * `:symbol` is the currency symbol. Optional. * `:narrow_symbol` is an alternative narrow symbol. Optional. * `:round_nearest` is the rounding precision such as `0.05`. Optional. * `:alt_code` is an alternative currency code for application use. * `:cash_digits` is the precision of the currency when used as cash. Optional. * `:cash_round_nearest` is the rounding precision when used as cash such as `0.05`. Optional. ### Returns * `{:ok, Cldr.Currency.t}` or * `{:error, {exception, message}}` ### Examples iex> Cldr.Currency.new(:XAC, name: "XAC currency", digits: 0) {:ok, %Cldr.Currency{ code: :XAC, count: %{other: "XAC currency"}, name: "XAC currency", symbol: "XAC", to: nil, from: nil, digits: 0, tender: false, alt_code: :XAC, rounding: 0, narrow_symbol: nil, cash_digits: 0, cash_rounding: nil, iso_digits: 0, decimal_separator: nil, grouping_separator: nil }} iex> Cldr.Currency.new(:QFFP, name: "QANTAS Frequent Flyer Points", digits: 0) {:ok, %Cldr.Currency{ code: :QFFP, count: %{other: "QANTAS Frequent Flyer Points"}, name: "QANTAS Frequent Flyer Points", symbol: "QFFP", to: nil, from: nil, digits: 0, tender: false, alt_code: :QFFP, rounding: 0, narrow_symbol: nil, cash_digits: 0, cash_rounding: nil, iso_digits: 0, decimal_separator: nil, grouping_separator: nil }} iex> Cldr.Currency.new(:XBC) {:error, {Cldr.CurrencyAlreadyDefined, "Currency :XBC is already defined."}} iex> MyApp.Cldr.Currency.new(:XAB, name: "Private Use Name") {:error, "Required options are missing. Required options are [:name, :digits]"} iex> Cldr.Currency.new(:ZAA, name: "Invalid Private Use Name", digits: 0) {:error, {Cldr.UnknownCurrencyError, "The currency :ZAA is unknown"}} # `pluralize` ```elixir @spec pluralize(pos_integer(), currency_code(), Cldr.backend(), Keyword.t()) :: {:ok, String.t()} | {:error, {module(), String.t()}} ``` Returns the appropriate currency display name for the `currency`, based on the plural rules in effect for the `locale`. ### Arguments * `number` is an integer, float or `Decimal`. * `currency` is any currency returned by `Cldr.Currency.known_currencies/0`. * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. * `options` is a keyword list of options. ### Options * `:locale` is any locale returned by `Cldr.Locale.new!/2`. The default is `.get_locale/1`. ### Returns * `{:ok, plural_string}` or * `{:error, {exception, message}}` ### Examples iex> Cldr.Currency.pluralize(1, :USD, MyApp.Cldr) {:ok, "US dollar"} iex> Cldr.Currency.pluralize(3, :USD, MyApp.Cldr) {:ok, "US dollars"} iex> Cldr.Currency.pluralize(12, :USD, MyApp.Cldr, locale: :zh) {:ok, "美元"} iex> Cldr.Currency.pluralize(12, :USD, MyApp.Cldr, locale: :fr) {:ok, "dollars des États-Unis"} iex> Cldr.Currency.pluralize(1, :USD, MyApp.Cldr, locale: :fr) {:ok, "dollar des États-Unis"} # `private_currencies` ```elixir @spec private_currencies() :: %{required(currency_code()) => t()} ``` Returns a map of private currencies. These comprise all currencies created with `Cldr.Currency.new/2`. # `private_currency_codes` ```elixir @spec private_currency_codes() :: [atom()] ``` Returns a list of all private currency codes. # `string_comparator` # `strings_for_currency` ```elixir @spec strings_for_currency( t(), Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), Cldr.backend() ) :: [ String.t() ] ``` Returns the strings associated with a currency in a given locale. ### Arguments * `currency` is an ISO4217 currency code * `locale` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`. * `backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module ### Returns * A list of strings or * `{:error, {exception, reason}}` ### Example iex> Cldr.Currency.strings_for_currency(:AUD, "en", MyApp.Cldr) |> Enum.sort ["a$", "aud", "australian dollar", "australian dollars"] iex> Cldr.Currency.strings_for_currency(:AUD, "de", MyApp.Cldr) |> Enum.sort ["au$", "aud", "australische dollar", "australischer dollar"] iex> Cldr.Currency.strings_for_currency(:AUD, "zh", MyApp.Cldr) |> Enum.sort ["au$", "aud", "澳大利亚元"] # `tender?` ```elixir @spec tender?(currency :: t()) :: boolean() ``` Returns a boolean indicating if a given currency is legal tender. Legal tender is anything recognized by law as a means to settle a public or private debt or meet a financial obligation. ### Arguments * `currency` is a `t:Cldr.Currency.t/0` ### Returns * `true` or `false` # `territory_currencies` Returns a mapping of all ISO3166 territory codes and a list of historic and the current currency for those territories. ### Example iex> Cldr.Currency.territory_currencies() |> Map.get(:LT) %{ EUR: %{from: ~D[2015-01-01], to: nil}, LTL: %{from: nil, to: ~D[2014-12-31]}, LTT: %{from: nil, to: ~D[1993-06-25]}, SUR: %{from: nil, to: ~D[1992-10-01]} } # `territory_currencies` ```elixir @spec territory_currencies(territory()) :: {:ok, map()} | {:error, {module(), String.t()}} ``` Returns a list of currencies associated with a given territory. ### Arguments * `territory` is any valid ISO 3166 Alpha-2 territory code. See `Cldr.validate_territory/1`. ### Returns * `{:ok, map}` where `map` has as its key a `t:Cldr.Currency.t/0` struct and the value is a map of validity dates for that currency; or * `{:error, {exception, reason}}` ### Example iex> Cldr.Currency.territory_currencies(:LT) {:ok, %{ EUR: %{from: ~D[2015-01-01], to: nil}, LTL: %{from: nil, to: ~D[2014-12-31]}, LTT: %{from: nil, to: ~D[1993-06-25]}, SUR: %{from: nil, to: ~D[1992-10-01]} }} # `territory_currencies!` ```elixir @spec territory_currencies!(territory()) :: map() | no_return() ``` Returns a list of currencies associated with a given territory. ### Arguments * `territory` is any valid ISO 3166 Alpha-2 territory code. See `Cldr.validate_territory/1`. ### Returns * `map` where `map` has as its key a `t:Cldr.Currency.t/0` struct and the value is a map of validity dates for that currency; or * raises an exception. ### Example iex> Cldr.Currency.territory_currencies!(:LT) %{ EUR: %{from: ~D[2015-01-01], to: nil}, LTL: %{from: nil, to: ~D[2014-12-31]}, LTT: %{from: nil, to: ~D[1993-06-25]}, SUR: %{from: nil, to: ~D[1992-10-01]} } # `unannotated?` ```elixir @spec unannotated?(currency :: t()) :: boolean() ``` Returns a boolean indicating if a given currency is unannotated. Annotated means that the currency description has annotations (comments inside parenthesis). This is mostly found in currency codes used as financial instruments (not legal tender). ### Arguments * `currency` is a `t:Cldr.Currency.t/0` ### Returns * `true` or `false` # `validate_currency` Validate an ISO4217 or custom currency code and return its canonical code. If the currency code is a custom code it must also have been created with `Cldr.Currency.new/2`. ### Arguments * `currency_code` is any ISO4217 currency code or a custom currency code as a string or an atom. ### Returns * `{:ok, currency_code}` or * `{:error, {exception, reason}}` ### Example iex> Cldr.Currency.validate_currency("AUD") {:ok, :AUD} # `validate_new_currency` ```elixir @spec validate_new_currency(currency_code()) :: {:ok, currency_code()} | {:error, {module(), String.t()}} ``` Determines is a new currency is already defined. ### Example iex> Cldr.Currency.validate_new_currency(:XAD) {:ok, :XAD} iex> Cldr.Currency.validate_new_currency(:USD) {:error, {Cldr.CurrencyAlreadyDefined, "Currency :USD is already defined."}} --- *Consult [api-reference.md](api-reference.md) for complete listing*