Forex.Currency (Forex v1.1.2)

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.

Summary

Types

code()

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

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

output_amount()

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

t()

Functions

all(keys \\ :atoms)

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

available(keys \\ :atoms)

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(keys \\ :atoms)

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(rates, amount, from_currency, to_currency, opts \\ [])

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

exchange_rates!(rates, amount, from_currency, to_currency, opts \\ [])

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

exists?(iso_code)

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

get(iso_code)

Get the currency information for the given ISO code.

get!(iso_code)

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(eur_rates, base_currency)

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

rebase(rates, base)

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

validate_currencies(from, to)

Types

code()

@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()

@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()

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

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

t()

@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()
}

Functions

all(keys \\ :atoms)

@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(keys \\ :atoms)

@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(keys \\ :atoms)

@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(rates, amount, from_currency, to_currency, opts \\ [])

@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!(rates, amount, from_currency, to_currency, opts \\ [])

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

exists?(iso_code)

@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(iso_code)

@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!(iso_code)

@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(eur_rates, base_currency)

@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(rates, base)

@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(from, to)

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