# `Cldr.Currency`
[🔗](https://github.com/elixir-cldr/cldr_currencies/blob/v2.17.2/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`.

* `:fallback` is a boolean indicating whether, when no localised data exists
  for the currency in the requested locale, the function should search the
  locale's CLDR fallback chain (parent locales) for localised data. The
  default is `false`.

### Returns

* `{:ok, currency}` or

* `{:error, {exception, reason}}`. In particular, when the currency is a
  valid ISO 4217 code but no localised data exists for it in the requested
  locale (and `:fallback` is `false` or the fallback chain yields nothing),
  the error is `{Cldr.CurrencyNotLocalized, _}`.

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

    iex> Cldr.Currency.display_name! "ZZZ", backend: MyApp.Cldr
    ** (Cldr.UnknownCurrencyError) The currency "ZZZ" is unknown

# `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 `<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"}

# `private_currencies`

```elixir
@spec private_currencies() :: %{required(currency_code()) =&gt; 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*