# `Money.Currency`
[🔗](https://github.com/ex-money/money/blob/v6.3.1/lib/money/currency.ex#L1)

Functions to manage currencies including ISO 4217 currencies
and custom (private-use) currencies.

Custom currencies can be created at runtime using `new/2` and
are stored in `Money.Currency.Store` for fast concurrent access.

# `currency_for_code`

```elixir
@spec currency_for_code(atom() | String.t()) ::
  {:ok, Localize.Currency.t()} | {:error, {module(), String.t()}}
```

Returns the currency definition for a currency code.

The lookup checks the locale-aware currency data first and then falls back
to the custom currency store. Unknown codes never create new atoms.

The currency data is read in the process locale (`Localize.get_locale/0`).
A locale lists only some currencies, so one it does not list is read from
the locale's parents and then the default locale: its digits are its own
in every locale, and only its names and symbols come from elsewhere.

### Arguments

* `code` is an ISO 4217 currency code, or a custom or private currency code,
  as an atom or a string.

### Returns

* `{:ok, currency}` where `currency` is a `t:Localize.Currency.t/0` struct.

* `{:error, {Money.UnknownCurrencyError, message}}` if `code` is not a known
  or registered currency.

### Examples

    iex> {:ok, currency} = Money.Currency.currency_for_code(:USD)
    iex> currency.code
    :USD

    iex> Money.Currency.currency_for_code(:NotACurrency)
    {:error, {Money.UnknownCurrencyError, "The currency :NotACurrency is not known."}}

# `known_current_currencies`

```elixir
@spec known_current_currencies() :: [atom(), ...]
```

Returns the list of currently active ISO 4217 currency codes.

### Returns

* a list of the ISO 4217 currency codes that are currently active.

### Examples

    iex> Money.Currency.known_current_currencies()
    [:AED, :AFN, :ALL, :AMD, :AOA, :ARS, :AUD, :AWG, :AZN, :BAM, :BBD, :BDT, :BHD,
     :BIF, :BMD, :BND, :BOB, :BOV, :BRL, :BSD, :BTN, :BWP, :BYN, :BZD, :CAD, :CDF,
     :CHE, :CHF, :CHW, :CLF, :CLP, :CNY, :COP, :COU, :CRC, :CUP, :CVE, :CZK, :DJF,
     :DKK, :DOP, :DZD, :EGP, :ERN, :ETB, :EUR, :FJD, :FKP, :GBP, :GEL, :GHS, :GIP,
     :GMD, :GNF, :GTQ, :GYD, :HKD, :HNL, :HTG, :HUF, :IDR, :ILS, :INR, :IQD, :IRR,
     :ISK, :JMD, :JOD, :JPY, :KES, :KGS, :KHR, :KMF, :KPW, :KRW, :KWD, :KYD, :KZT,
     :LAK, :LBP, :LKR, :LRD, :LSL, :LYD, :MAD, :MDL, :MGA, :MKD, :MMK, :MNT, :MOP,
     :MRU, :MUR, :MVR, :MWK, :MXN, :MXV, :MYR, :MZN, :NAD, :NGN, :NIO, :NOK, :NPR,
     :NZD, :OMR, :PAB, :PEN, :PGK, :PHP, :PKR, :PLN, :PYG, :QAR, :RON, :RSD, :RUB,
     :RWF, :SAR, :SBD, :SCR, :SDG, :SEK, :SGD, :SHP, :SLE, :SOS, :SRD, :SSP, :STN,
     :SVC, :SYP, :SZL, :THB, :TJS, :TMT, :TND, :TOP, :TRY, :TTD, :TWD, :TZS, :UAH,
     :UGX, :USD, :USN, :UYI, :UYU, :UYW, :UZS, :VED, :VES, :VND, :VUV, :WST, :XAF,
     :XAG, :XAU, :XBA, :XBB, :XBC, :XBD, :XCD, :XCG, :XDR, :XOF, :XPD, :XPF, :XPT,
     :XSU, :XTS, :XUA, :XXX, :YER, :ZAR, :ZMW, :ZWG]

# `known_historic_currencies`

```elixir
@spec known_historic_currencies() :: [atom(), ...]
```

Returns the list of historic ISO 4217 currency codes.

### Returns

* a list of historic (no longer active) ISO 4217 currency codes.

### Examples

    iex> :DEM in Money.Currency.known_historic_currencies()
    true

    iex> :EUR in Money.Currency.known_historic_currencies()
    false

# `known_tender_currencies`

```elixir
@spec known_tender_currencies() :: [atom(), ...]
```

Returns the list of legal tender ISO 4217 currency codes.

### Returns

* a list of the ISO 4217 currency codes that are legal tender.

### Examples

    iex> :EUR in Money.Currency.known_tender_currencies()
    true

    iex> :ABC in Money.Currency.known_tender_currencies()
    false

# `new`

```elixir
@spec new(atom() | String.t(), Keyword.t()) ::
  {:ok, Localize.Currency.t()} | {:error, Exception.t()}
```

Creates a new private-use or custom currency and stores it in the currency store.

Currencies use the `Localize.Currency` struct as the data shape
to maintain compatibility with locale-aware formatting.

### Arguments

* `currency_code` is an atom or string currency code. Must be either:

  * A **private-use** code conforming to ISO 4217: 3 characters starting
    with `X` followed by 2 uppercase letters (e.g. `:XBT`, `:XAU`).

  * A **custom** code: 4–10 uppercase alphanumeric characters starting
    with a letter (e.g. `:QFFP`, `:BTC1`).

* `options` is a keyword list of options.

### Options

* `:name` is the display name of the currency. Required.

* `:digits` is the decimal precision. The default is `2`.

* `:symbol` is the currency symbol (e.g. `"₿"`, `"Ξ"`).
  Defaults to the uppercase currency code string.

* `: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. Optional.

* `:cash_digits` is the precision when used as cash. Defaults to `:digits`.

* `:cash_round_nearest` is the cash rounding precision. Optional.

* `:tender` is a boolean indicating whether the currency is
  legal tender. The default is `false`.

* `:count` is a map of pluralized name forms (e.g.
  `%{one: "Bitcoin", other: "Bitcoins"}`). Defaults to
  `%{other: name}`.

### Returns

* `{:ok, Localize.Currency.t()}` on success.

* `{:error, exception}` if the code is invalid or already defined.

### Examples

    iex> Money.Currency.new(:XAC, name: "XAC currency", digits: 0)
    {:ok,
     %Localize.Currency{
      code: :XAC,
      alt_code: :XAC,
      name: "XAC currency",
      symbol: "XAC",
      narrow_symbol: nil,
      digits: 0,
      rounding: 0,
      cash_digits: 0,
      cash_rounding: nil,
      iso_digits: 0,
      decimal_separator: nil,
      grouping_separator: nil,
      tender: false,
      count: %{other: "XAC currency"},
      from: nil,
      to: nil
    }}

# `private_currencies`

```elixir
@spec private_currencies() :: %{required(atom()) =&gt; Localize.Currency.t()}
```

Returns a map of all custom currencies.

### Returns

* A map of `%{currency_code => Localize.Currency.t()}`.

# `private_currency_codes`

```elixir
@spec private_currency_codes() :: [atom()]
```

Returns a list of all custom currency codes.

### Returns

* A list of atom currency codes.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
