Search documentation of bb

# BB.Cldr.Currency (bb v0.8.0)

View Source

# Summary

## Functions

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

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

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

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

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

Returns the currency metadata for the requested currency code.

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

Returns the currency metadata for the requested currency code.

currency_from_locale(locale)

Returns the effective currency for a given locale

currency_history_for_locale(language_tag)

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

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

Returns a map that matches a currency string to a currency code.

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

Returns a map that matches a currency string to a currency code or raises an exception.

current_currency_from_locale(locale)

Returns the current currency for a given locale.

current_territory_currencies()

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

known_currencies()

See `BB.Cldr.Currency.known_currency_codes/0`.

known_currency?(code)

See `BB.Cldr.Currency.known_currency_code?/1`.

known_currency_code(currency_code)

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

known_currency_code?(currency_code)

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

known_currency_codes()

Returns a list of all known currency codes.

new(currency, options \\ [])

Returns a `Currency` struct created from the arguments.

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

Returns the appropriate currency display name for the `currency`, based on the plural rules in effect for the `locale`.

strings_for_currency(currency, locale)

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

# Functions

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

    @spec currencies_for_locale(
      Cldr.Locale.locale_reference(),
      only :: Cldr.Currency.filter(),
      except :: Cldr.Currency.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 `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
     },
     ...
    }}

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

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

}

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

    @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> BB.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> BB.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
    }}

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

(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

- `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> BB.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> BB.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
    }

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

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

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

# currency_history_for_locale(language_tag)

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

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

    @spec currency_strings(
      Cldr.Locale.locale_reference(),
      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,
       ...
      }}

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

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

# current_currency_from_locale(locale)

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

# current_territory_currencies()

(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

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

## Example

    iex> BB.Cldr.Currency.current_territory_currencies()

# known_currencies()

See `BB.Cldr.Currency.known_currency_codes/0`.

# known_currency?(code)

See `BB.Cldr.Currency.known_currency_code?/1`.

# known_currency_code(currency_code)

    @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> BB.Cldr.Currency.known_currency_code("AUD")
    {:ok, :AUD}

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

# known_currency_code?(currency_code)

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

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

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

# known_currency_codes()

    @spec known_currency_codes() :: [Cldr.Currency.code(), ...]

Returns a list of all known currency codes.

## Example

    iex> BB.Cldr.Currency.known_currency_codes()

# new(currency, options \\ [])

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

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

    @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 `BB.Cldr.get_locale/0`

## Returns

- `{:ok, plural_string}` or

- `{:error, {exception, message}}`

## Examples

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

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

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

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

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

# strings_for_currency(currency, locale)

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")
    ...> |> Enum.sort()
    ["a$", "aud", "australian dollar", "australian dollars"]