@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

• 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

• {:ok, currency_map} or

• {:error, {exception, reason}}

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

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

• {: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
},
...

}

@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

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

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

@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

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

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

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} = Plausible.Cldr.validate_locale("en")
iex> Plausible.Cldr.Currency.currency_from_locale locale
:USD

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

iex> Plausible.Cldr.Currency.currency_from_locale("en-GB")
:GBP

@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

• 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

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

@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

• 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

• {:ok, currency_string_map} or

• {:error, {exception, reason}}

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

@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

• 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

• {:ok, currency_string_map} or

• raises an exception

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

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

• 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

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

iex> MyApp.Cldr.Currency.current_currency_from_locale("en-AU")
:AUD

@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

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

Example

iex> Plausible.Cldr.Currency.current_territory_currencies()

See Plausible.Cldr.Currency.known_currency_codes/0.

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

@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

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

Returns

• {:ok, currency_code} or

• {:error, {exception, reason}}

Examples

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

iex> Plausible.Cldr.Currency.known_currency_code("GGG")
{:error, {Cldr.UnknownCurrencyError, "The currency \"GGG\" is invalid"}}

@spec known_currency_code?(Cldr.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> Plausible.Cldr.Currency.known_currency_code?("AUD")
true

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

iex> Plausible.Cldr.Currency.known_currency_code?(:XCV)
false

@spec known_currency_codes() :: [atom()]

Returns a list of all known currency codes.

Example

iex> Plausible.Cldr.Currency.known_currency_codes()

@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

• 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

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

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

• {:error, {exception, message}}

Example

iex> Plausible.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> Plausible.Cldr.Currency.new(:XAE, name: "XAE", digits: 0)
{:error, {Cldr.CurrencyAlreadyDefined, "Currency :XAE is already defined."}}

@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

• number is an integer, float or Decimal

• currency is any currency returned by Cldr.Currency.known_currencies/0

• options is a keyword list of options

Options

• 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. The default is Plausible.Cldr.get_locale/0

Returns

• {:ok, plural_string} or

• {:error, {exception, message}}

Examples

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

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

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

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

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

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 MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

Returns

• A list of strings or

• {:error, {exception, reason}}

Example

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