Cldr.Currency (Cldr Currencies v2.8.0) 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 a map of the metadata for all currencies for a given locale.
Returns a map of the metadata for all currencies for a given locale and raises on error.
Return only those currencies meeting the filter criteria.
Returns the currency metadata for the requested currency code.
Returns the effective currency format for a given locale
Returns the effective currency for a given locale
Returns the effective currency for a given locale
Returns a list of historic and the current currency for a given locale.
Returns a map that matches a currency string to a currency code.
Returns a map that matches a currency string to a currency code or raises an exception.
Returns the current currency for a given territory.
Returns the current currency from a given locale.
Returns a 2-tuple indicating if the supplied currency code is known.
Returns a boolean indicating if the supplied currency code is known.
Returns a list of all known currency codes.
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
.
Returns a map of private currencies.
Returns a list of all private currency codes.
Returns the strings associated with a currency in a given locale.
Returns a mapping of all ISO3166 territory codes and a list of historic and the current currency for those territories.
Determines is a new currency is already defined.
Link to this section Types
Specs
code() :: atom()
Specs
currency_status() :: :all | :current | :historic | :tender | :unannotated | :private
Specs
filter() :: [currency_status() | code()] | currency_status() | code()
Specs
format() :: :standard | :accounting | :short | :long | :percent | :scientific
Specs
t() :: %Cldr.Currency{ alt_code: code(), cash_digits: non_neg_integer(), cash_rounding: non_neg_integer(), code: code(), count: %{}, digits: non_neg_integer(), from: Calendar.year(), iso_digits: non_neg_integer(), name: String.t(), narrow_symbol: String.t(), rounding: non_neg_integer(), symbol: String.t(), tender: boolean(), to: Calendar.year() }
Link to this section Functions
currencies_for_locale(locale, backend, only \\ :all, except \\ nil)
View SourceSpecs
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 byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
backend
is any module that includesuse Cldr
and therefore is aCldr
backend modulecurrency_status
is:all
,:current
,:historic
,unannotated
or:tender
; or a list of one or more status. The default is:all
. SeeCldr.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!(locale, backend, only \\ :all, except \\ nil)
View SourceSpecs
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 byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
backend
is any module that includesuse Cldr
and therefore is aCldr
backend modulecurrency_status
is:all
,:current
,:historic
,unannotated
or:tender
; or a list of one or more status. The default is:all
. SeeCldr.Currency.currency_filter/2
.
Returns
{:ok, currency_map}
orraises 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
},
...
}
Return only those currencies meeting the filter criteria.
Arguments
currency
is aCldr.Currency.t
, a list ofCldr.Currency.t
or a map where the values of each item is aCldr.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 isnil
Currency Status
A currency may be in current use, 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.
Specs
currency_for_code(code(), Cldr.backend(), Keyword.t()) :: {:ok, t()} | {:error, {module(), String.t()}}
Returns the currency metadata for the requested currency code.
Arguments
currency_code
is abinary
oratom
representation of an ISO 4217 currency code.backend
is any module that includesuse Cldr
and therefore is aCldr
backend moduleoptions
is aKeyword
list of options.
Options
:locale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
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
}}
Returns the effective currency format for a given locale
Arguments
locale
aCldr.LanguageTag
struct returned byCldr.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
Returns the effective currency for a given locale
Arguments
locale
is aCldr.LanguageTag
struct returned byCldr.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
Returns the effective currency for a given locale
Arguments
locale
is any valid locale name returned byCldr.known_locale_names/1
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.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
Specs
currency_history_for_locale(Cldr.LanguageTag.t()) :: {:ok, map()} | {:error, {atom(), binary()}}
Returns a list of historic and the current currency for a given locale.
Arguments
locale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
backend
is any module that includesuse Cldr
and therefore is aCldr
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]}
}
}
Specs
currency_history_for_locale(Cldr.Locale.locale_name(), Cldr.backend()) :: {:ok, map()} | {:error, {module(), String.t()}}
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 byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
.:only
is:all
,:current
,:historic
,unannotated
or:tender
; or a list of one or more status The default is:all
. SeeCldr.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,
...
}}
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 byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
.currency_status
is:all
,:current
,:historic
,unannotated
or:tender
; or a list of one or more status. The default is:all
. SeeCldr.Currency.currency_filter/2
.
Returns
{:ok, currency_string_map}
orraises 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,
...
}
Specs
current_currency_for_territory(Cldr.territory()) :: code() | nil | {:error, {module(), String.t()}}
Returns the current currency for a given territory.
Arguments
territory
is any valid territory name returned byCldr.known_territories/0
Examples
iex> Cldr.Currency.current_currency_for_territory :US
:USD
iex> Cldr.Currency.current_currency_for_territory :AU
:AUD
Specs
current_currency_from_locale(Cldr.LanguageTag.t()) :: any()
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 byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
backend
is any module that includesuse Cldr
and therefore is aCldr
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
Specs
current_currency_from_locale(Cldr.Locale.locale_name(), Cldr.backend()) :: code() | nil | {:error, {module(), String.t()}}
Specs
Returns a 2-tuple indicating if the supplied currency code is known.
Arguments
currency_code
is abinary
oratom
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 invalid"}}
Specs
Returns a boolean indicating if the supplied currency code is known.
Arguments
currency_code
is abinary
oratom
representing an ISO4217 currency code
Returns
true
orfalse
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
Specs
known_currency_codes() :: [atom()]
Returns a list of all known currency codes.
Example
iex> Cldr.Currency.known_currency_codes |> Enum.count
303
Specs
Returns a Currency
struct created from the arguments.
Arguments
currency
is a private use currency code in a format defined by ISO4217 which isX
followed by two alphanumeric characters.options
is a map of options representing the optional elements of theCldr.Currency.t
struct.
Options
:name
is the name of the currenct. 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 as0.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 as0.05
. Optional.
Returns
{:ok, Cldr.Currency.t}
or{:error, {exception, message}}
Example
iex> Cldr.Currency.new(:XAA, name: "XAA currency", digits: 0)
{:ok,
%Cldr.Currency{
alt_code: :XAA,
cash_digits: 0,
cash_rounding: nil,
code: :XAA,
count: %{other: "XAA currency"},
digits: 0,
from: nil,
iso_digits: 0,
name: "XAA currency",
narrow_symbol: nil,
rounding: 0,
symbol: "XAA",
tender: false,
to: nil
}}
iex> Cldr.Currency.new(:XBC)
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :XBC is already defined."}}
iex> MyApp.Cldr.Currency.new(:XAA, 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 invalid"}}
Specs
pluralize(pos_integer(), 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 orDecimal
currency
is any currency returned byCldr.Currency.known_currencies/0
locale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
backend
is any module that includesuse Cldr
and therefore is aCldr
backend moduleoptions
is a keyword list of options
Options
:locale
is any locale returned byCldr.Locale.new!/2
. The default is<backend>.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"}
Specs
Returns a map of private currencies.
These comprise all currencies created with
Cldr.Currency.new/2
.
Specs
private_currency_codes() :: [atom()]
Returns a list of all private currency codes.
Returns the strings associated with a currency in a given locale.
Arguments
currency
is an ISO4217 currency codelocale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module
Returns
A list of strings or
{:error, {exception, reason}}
Example
iex> Cldr.Currency.strings_for_currency :AUD, "en", MyApp.Cldr
["a$", "australian dollars", "aud", "australian dollar"]
iex> Cldr.Currency.strings_for_currency :AUD, "de", MyApp.Cldr
["australische dollar", "australischer dollar", "au$", "aud"]
iex> Cldr.Currency.strings_for_currency :AUD, "zh", MyApp.Cldr
["澳大利亚元", "au$", "aud"]
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]}
}
Specs
Determines is a new currency is already defined.
Example
iex> Cldr.Currency.validate_new_currency :XAC
{:ok, :XAC}
iex> Cldr.Currency.validate_new_currency :USD
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :USD is already defined."}}