View Source ExCatalog.Cldr.Currency (ex_catalog v1.5.6)

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.

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 locale.

Returns a mapping from a territory code to its current currency code.

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 the strings associated with a currency in a given locale.

Link to this section Functions

Link to this function

currencies_for_locale(locale, only \\ :all, except \\ nil)

View Source
@spec currencies_for_locale(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  only :: Cldr.Currency.filter(),
  except :: Cldr.Currency.filter()
) :: {:ok, map()} | {:error, {module(), String.t()}}
@spec currencies_for_locale(
  Cldr.Locale.locale_name() | Cldr.LanguageTag.t(),
  only :: Cldr.Currency.filter(),
  except :: Cldr.Currency.filter()
) :: map() | no_return()

Returns a map of the metadata for all currencies for a given locale.

arguments

Arguments

  • locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

  • 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

Returns

  • {:ok, currency_map} or

  • {:error, {exception, reason}}

example

Example

MyApp.Cldr.Currency.currencies_for_locale("en") => {: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
 },
 ...
}}
Link to this function

currencies_for_locale!(locale, only \\ :all, except \\ nil)

View Source

Returns a map of the metadata for all currencies for a given locale and raises on error.

arguments

Arguments

  • locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

  • 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

Returns

  • {:ok, currency_map} or

  • raises an exception

example

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
},
...

}

Link to this function

currency_for_code(currency_or_currency_code, options \\ [locale: ExCatalog.Cldr.default_locale()])

View Source
@spec currency_for_code(Cldr.Currency.code() | Cldr.Currency.t(), Keyword.t()) ::
  {:ok, Cldr.Currency.t()} | {:error, {module(), String.t()}}

Returns the currency metadata for the requested currency code.

arguments

Arguments

  • currency_or_currency_code is a binary or atom representation of an ISO 4217 currency code, or a %Cldr.Currency{} struct.

options

Options

returns

Returns

  • A {:ok, currency} or

  • {:error, {exception, reason}}

examples

Examples

iex> ExCatalog.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> ExCatalog.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

currency_for_code!(currency_or_currency_code, options \\ [locale: ExCatalog.Cldr.default_locale()])

View Source (since 2.14.0)
@spec currency_for_code!(Cldr.Currency.code() | Cldr.Currency.t(), Keyword.t()) ::
  Cldr.Currency.t() | no_return()

Returns the currency metadata for the requested currency code.

arguments

Arguments

  • currency_or_currency_code is a binary or atom representation of an ISO 4217 currency code, or a %Cldr.Currency{} struct.

options

Options

returns

Returns

  • A t:Cldr.Current.t/0 or

  • raises an exception

examples

Examples

iex> ExCatalog.Cldr.Currency.currency_for_code!("AUD")
%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> ExCatalog.Cldr.Currency.currency_for_code!("THB")
%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

currency_from_locale(locale)

View Source

Returns the effective currency for a given locale

arguments

Arguments

returns

Returns

  • A ISO 4217 currency code as an upcased atom

examples

Examples

iex> {:ok, locale} = ExCatalog.Cldr.validate_locale("en")
iex> ExCatalog.Cldr.Currency.currency_from_locale locale
:USD

iex> {:ok, locale} = ExCatalog.Cldr.validate_locale("en-AU")
iex> ExCatalog.Cldr.Currency.currency_from_locale locale
:AUD

iex> ExCatalog.Cldr.Currency.currency_from_locale("en-GB")
:GBP
Link to this function

currency_history_for_locale(language_tag)

View Source
@spec currency_history_for_locale(Cldr.LanguageTag.t() | Cldr.Locale.locale_name()) ::
  {:ok, map()} | {:error, {module(), String.t()}}

Returns a list of historic and the current currency for a given locale.

arguments

Arguments

  • locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

example

Example

iex> MyApp.Cldr.Currency.currency_history_for_locale("en")
{:ok,
    %{
    USD: %{from: ~D[1792-01-01], to: nil},
    USN: %{tender: false},
    USS: %{from: nil, tender: false, to: ~D[2014-03-01]}
  }
}
Link to this function

currency_strings(locale, only \\ :all, except \\ nil)

View Source
@spec currency_strings(
  Cldr.LanguageTag.t() | Cldr.Locale.locale_name(),
  only :: Cldr.Currency.filter(),
  except :: Cldr.Currency.filter()
) :: {: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

Arguments

  • locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

  • 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

Returns

  • {:ok, currency_string_map} or

  • {:error, {exception, reason}}

example

Example

MyApp.Cldr.Currency.currency_strings("en")
=> {: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,
   ...
  }}
Link to this function

currency_strings!(locale_name, only \\ :all, except \\ nil)

View Source
@spec currency_strings!(
  Cldr.LanguageTag.t() | Cldr.Locale.locale_name(),
  only :: Cldr.Currency.filter(),
  except :: Cldr.Currency.filter()
) :: map() | no_return()

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

Arguments

  • locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

  • 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

Returns

  • {:ok, currency_string_map} or

  • raises an exception

example

Example

MyApp.Cldr.Currency.currency_strings!("en")
=> %{
  "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,
  ...
 }
Link to this function

current_currency_from_locale(locale)

View Source

Returns the current currency for 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

Arguments

  • locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

example

Example

iex> MyApp.Cldr.Currency.current_currency_from_locale("en")
:USD

iex> MyApp.Cldr.Currency.current_currency_from_locale("en-AU")
:AUD
Link to this function

current_territory_currencies()

View Source (since 2.15.0)
@spec current_territory_currencies() :: %{
  required(Cldr.Locale.territory_code()) => Cldr.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

Returns

  • A map of {territory_code => Cldr.Currency.t}

example

Example

iex> ExCatalog.Cldr.Currency.current_territory_currencies()

See ExCatalog.Cldr.Currency.known_currency_codes/0.

See ExCatalog.Cldr.Currency.known_currency_code?/1.

Link to this function

known_currency_code(currency_code)

View Source
@spec known_currency_code(Cldr.Currency.code()) ::
  {:ok, Cldr.Currency.code()} | {:error, {module(), String.t()}}

Returns a 2-tuple indicating if the supplied currency code is known.

arguments

Arguments

  • currency_code is a binary or atom representing an ISO4217 currency code

returns

Returns

  • {:ok, currency_code} or

  • {:error, {exception, reason}}

examples

Examples

iex> ExCatalog.Cldr.Currency.known_currency_code("AUD")
{:ok, :AUD}

iex> ExCatalog.Cldr.Currency.known_currency_code("GGG")
{:error, {Cldr.UnknownCurrencyError, "The currency \"GGG\" is invalid"}}
Link to this function

known_currency_code?(currency_code)

View Source
@spec known_currency_code?(Cldr.Currency.code()) :: boolean()

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

arguments

Arguments

  • currency_code is a binary or atom representing an ISO4217 currency code

returns

Returns

  • true or false

examples

Examples

iex> ExCatalog.Cldr.Currency.known_currency_code?("AUD")
true

iex> ExCatalog.Cldr.Currency.known_currency_code?("GGG")
false

iex> ExCatalog.Cldr.Currency.known_currency_code?(:XCV)
false
@spec known_currency_codes() :: [atom()]

Returns a list of all known currency codes.

example

Example

iex> ExCatalog.Cldr.Currency.known_currency_codes()
Link to this function

new(currency, options \\ [])

View Source
@spec new(Cldr.Currency.code(), map() | Keyword.t()) ::
  {:ok, Cldr.Currency.t()} | {:error, {module(), String.t()}}

Returns a Currency struct created from the arguments.

arguments

Arguments

  • currency is a private use currency code in a format defined by ISO4217 which is X followed by two alphanumeric characters.

  • options is a map of options representing the optional elements of the Cldr.Currency.t struct.

options

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_rounding_nearest is the rounding precision when used as cash such as 0.05. Optional.

returns

Returns

  • {:ok, Cldr.Currency.t} or

  • {:error, {exception, message}}

example

Example

iex> ExCatalog.Cldr.Currency.new(:XAE, name: "Custom Name", digits: 0)
{:ok,
 %Cldr.Currency{
   alt_code: :XAE,
   cash_digits: 0,
   cash_rounding: nil,
   code: :XAE,
   count: %{other: "Custom Name"},
   digits: 0,
   from: nil,
   iso_digits: 0,
   name: "Custom Name",
   narrow_symbol: nil,
   rounding: 0,
   symbol: "XAE",
   tender: false,
   to: nil
 }}
iex> MyApp.Cldr.Currency.new(:XAH, name: "Custom Name")
{:error, "Required options are missing. Required options are [:name, :digits]"}
iex> ExCatalog.Cldr.Currency.new(:XAE, name: "XAE", digits: 0)
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :XAE is already defined."}}
Link to this function

pluralize(number, currency, options \\ [])

View Source
@spec pluralize(pos_integer(), atom(), 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

Arguments

options

Options

returns

Returns

  • {:ok, plural_string} or

  • {:error, {exception, message}}

examples

Examples

iex> ExCatalog.Cldr.Currency.pluralize(1, :USD)
{:ok, "US dollar"}

iex> ExCatalog.Cldr.Currency.pluralize(3, :USD)
{:ok, "US dollars"}

iex> ExCatalog.Cldr.Currency.pluralize(12, :USD, locale: "zh")
{:ok, "美元"}

iex> ExCatalog.Cldr.Currency.pluralize(12, :USD, locale: "fr")
{:ok, "dollars des États-Unis"}

iex> ExCatalog.Cldr.Currency.pluralize(1, :USD, locale: "fr")
{:ok, "dollar des États-Unis"}
Link to this function

strings_for_currency(currency, locale)

View Source

Returns the strings associated with a currency in a given locale.

arguments

Arguments

  • currency is an ISO4217 currency code

  • locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

returns

Returns

  • A list of strings or

  • {:error, {exception, reason}}

example

Example

iex> MyApp.Cldr.Currency.strings_for_currency(:AUD, "en")
["a$", "australian dollars", "aud", "australian dollar"]