duff / currency_formatter

An Elixir function to format a number to a currency using ISO standards

CurrencyFormatter

This package offers an Elixir function to format a number to a currency using ISO standards.

The JSON iso data has been gracefully borrowed from the ruby money gem.

Examples :

Formatting cents to currency string

iex> CurrencyFormatter.format(123456)
"US$1,234.56"

iex> CurrencyFormatter.format(654321, :eur)
"€6.543,21"

iex> CurrencyFormatter.format(654321, "AUD")
"A$6,543.21"

Requesting formatting instructions for a currency

iex> CurrencyFormatter.instructions(:EUR)
%{"alternate_symbols" => [], "decimal_mark" => ",", "html_entity" => "€",
  "iso_code" => "EUR", "iso_numeric" => "978", "name" => "Euro", "priority" => 2,
  "smallest_denomination" => 1, "subunit" => "Cent", "subunit_to_unit" => 100,
  "symbol" => "€", "symbol_first" => true, "thousands_separator" => "."}

Get a map of all currencies and their instructions

iex> currencies = CurrencyFormatter.get_currencies()
iex> Enum.count(currencies)
172
iex> currencies["usd"]
%{"alternate_symbols" => ["US$"], "decimal_mark" => ".",
  "disambiguate_symbol" => "US$", "html_entity" => "$", "iso_code" => "USD",
  "iso_numeric" => "840", "name" => "United States Dollar", "priority" => 1,
  "smallest_denomination" => 1, "subunit" => "Cent", "subunit_to_unit" => 100,
  "symbol" => "$", "symbol_first" => true, "thousands_separator" => ","}

Getting a list of tuples for use with a select dropdown

iex> CurrencyFormatter.get_currencies_for_select()
["AED", "AFN", "ALL", ...]

iex> CurrencyFormatter.get_currencies_for_select(:names)
[{"AED", "United Arab Emirates Dirham"}, {"AFN", "Afghan Afghani"} , {"ALL", "Albanian Lek"}, ...]

iex> CurrencyFormatter.get_currencies_for_select(:symbols)
[{"AED", "د.إ"}, {"AFN", "؋"}, {"ALL", "L"}, ...]

iex> CurrencyFormatter.get_currencies_for_select(:disambiguate_symbols)
[[{"AED", "د.إ"}, {"AFN", "؋"}, {"ALL", "Lek"}, ...]

Get the disambiguous symbol of a currrency

iex> CurrencyFormatter.symbol(:AUD)
"A$"

Installation

As this is available in Hex, the package can be installed as:

1. Add currency_formatter to your list of dependencies in mix.exs:

def deps do
  [{:currency_formatter, "~> 0.4"}]
end

Setup

By default you will have 172 currencies available, there are two configuration options that can be set in your app's config.exs file to limit the number of currencies.

If you would like to limit the list to only include specific currencies, you can configure a whitelist by passing a list of ISO codes to include:

config :currency_formatter, :whitelist, ["EUR", "GBP", "USD"]

To exclude certain currencies from the list, you can configure a blacklist using a list of ISO codes to exclude:

config :currency_formatter, :blacklist, ["XDR", "XAG", "XAU"]

Documentation

API documentation is available at https://hexdocs.pm/currency_formatter and http://smeevil.github.io/currency_formatter