# `Forex.Currency`
[🔗](https://github.com/greven/forex/blob/1.1.2/lib/forex/currency.ex#L1)

This module provides curreny information and utility functions.

Only a subset of all the currencies are included in this module, since
these are the currencies supported by the European Central Bank (ECB)
exchange rates feed.

# `code`

```elixir
@type code() :: atom() | String.t()
```

The currency code is a three-letter code that represents a currency, in
accordance with the ISO 4217 standard. It can be either a string or an atom.
The code is case-insensitive, so `:usd` and `:USD` are equivalent.

# `input_amount`

```elixir
@type input_amount() :: number() | Decimal.t() | String.t()
```

The currency input amount can be a number, a Decimal value,
or a string representation of a number.

# `output_amount`

```elixir
@type output_amount() :: Decimal.t() | String.t()
```

A currency output amount can be a Decimal value
or a string representation of a number.

# `t`

```elixir
@type t() :: %Forex.Currency{
  alt_names: [String.t()],
  alt_symbols: [String.t()],
  iso_code: String.t(),
  iso_numeric: String.t(),
  name: String.t(),
  subunit: float(),
  subunit_name: String.t(),
  symbol: String.t()
}
```

# `all`

```elixir
@spec all(keys :: :atoms | :strings) :: %{required(code()) => t()}
```

Get all list of all currencies, including disabled currencies (necessary,
since historical rates may include disabled currencies in the past).

# `available`

```elixir
@spec available(keys :: :atoms | :strings) :: %{required(code()) => t()}
```

Get all list of all the available currencies (enabled currencies), that
is, all the currencies that are supported by the ECB at the present time.

# `disabled`

```elixir
@spec disabled(keys :: :atoms | :strings) :: %{required(code()) => t()}
```

Get all list of all the disabled currencies, that is,
all the currencies that are not supported by the ECB at the present time but
may have been supported in the past and are included in historical rates.

# `exchange_rates`

```elixir
@spec exchange_rates(
  rates :: {:ok, Forex.t()} | Forex.t() | %{required(code()) => input_amount()},
  amount :: input_amount(),
  from_currency :: code(),
  to_currency :: code(),
  opts :: [Forex.Options.currency_option()]
) :: {:ok, output_amount()} | {:error, term()}
```

Exchange a given amount from one currency to another using ECB rates.

The given rates should be a `Forex` struct (or an `{:ok, %{Forex}}` tuple) or
a map with the currency codes as keys and the corresponding rates as values.

## Options
* `:format` - Format of rate values The default value is `:decimal`.

* `:round` - Decimal places for rounding The default value is `5`.

# `exchange_rates!`

Like `exchange_rates/5`, but raises a `Forex.CurrencyError` if the exchange fails.

# `exists?`

```elixir
@spec exists?(code()) :: boolean()
```

Check if a currency with the given ISO exists, i.e.,
if it is supported by the European Central Bank (ECB) service.

Examples:

    iex> Forex.Currency.exists?(:eur)
    true
    iex> Forex.Currency.exists?("USD")
    true
    iex> Forex.Currency.exists?(:GBP)
    true
    iex> Forex.Currency.exists?(:xpt)
    false
    iex> Forex.Currency.exists?(:invalid)
    false
    iex> Forex.Currency.exists?(nil)
    false

# `get`

```elixir
@spec get(code()) :: {:ok, t()} | {:error, :not_found}
```

Get the currency information for the given ISO code.

Examples:

    iex> Forex.Currency.get(:eur)
    {:ok, %{name: "Euro", ...}}
    iex> Forex.Currency.get("USD")
    {:ok, %{name: "United States Dollar", ...}}
    iex> Forex.Currency.get(:GBP)
    {:ok, %{name: "British Pound Sterling", ...}}

# `get!`

```elixir
@spec get!(code()) :: t()
```

Get the currency information for the given ISO code.
The same as `get/1`, but raises a `Forex.CurrencyError` if the currency is not found.

# `maybe_rebase`

```elixir
@spec maybe_rebase(
  eur_rates :: [%{currency: code(), rate: String.t()}],
  base_currency :: code()
) ::
  {:ok, [%{currency: code(), rate: Decimal.t()}]}
  | {:error, :base_currency_not_found}
```

This function is used to rebase the rates to a new base currency.

The default base currency is `:EUR`, so if the base_currency is a different
currency, the rates will be converted to the new currency base.

# `rebase`

```elixir
@spec rebase(
  rates :: [%{currency: code(), rate: String.t()}],
  base :: code()
) :: [%{currency: code(), rate: Decimal.t()}]
```

Given a list of rates in the form of %{code() => Decimal.t()},
convert the rates to a new currency base.

# `validate_currencies`

```elixir
@spec validate_currencies(from :: code(), to :: code()) ::
  {:ok, {code(), code()}} | {:error, :invalid_currency}
```

---

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