Forex.Currency (Forex v0.2.1)

View Source

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

Functions

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

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.

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 a given amount from one currency to another using ECB rates.

Exchange a given amount from one currency to another using ECB rates. Like exchange/4, but raises a Forex.CurrencyError if the exchange fails.

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

Get the currency information for the given 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.

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

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

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(amount, from, to, opts \\ [])

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

Options

  • :format - Output format (:decimal or :string). Defaults to :decimal.
  • :round - Decimal places for rounding. Defaults to 5.

Examples

iex> Forex.exchange(100, :USD, :EUR)
{:ok, Decimal.new("95.28300")}

iex> Forex.exchange(100, "USD", "EUR", format: :string)
{:ok, "95.28300"}

iex> Forex.exchange(100, "INVALID", "EUR")
{:error, :invalid_currency}

exchange!(amount, from, to, opts \\ [])

Exchange a given amount from one currency to another using ECB rates. Like exchange/4, 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.

Example:

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)

Get the currency information for the given ISO code.

Example:

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)

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.

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)

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