money

# Introduction to Money

![Build status](https://github.com/ex-money/money/actions/workflows/ci.yml/badge.svg)
[![Hex.pm](https://img.shields.io/hexpm/v/ex_money.svg)](https://hex.pm/packages/ex_money)
[![Hex.pm](https://img.shields.io/hexpm/dw/ex_money.svg?)](https://hex.pm/packages/ex_money)
[![Hex.pm](https://img.shields.io/hexpm/dt/ex_money.svg?)](https://hex.pm/packages/ex_money)
[![Hex.pm](https://img.shields.io/hexpm/l/ex_money.svg)](https://hex.pm/packages/ex_money)

Money implements a set of functions to store, retrieve, convert and perform arithmetic
on a `t:Money.t/0` type that is composed of an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code, an [ISO 24165](https://www.iso.org/standard/80601.html) Digital Token Identifier (crypto currency) or a custom currency code with a currency amount.

Money is opinionated in the interests of serving as a dependable library that can underpin accounting and financial applications.

How is this opinion expressed?

1. Money must always have both a amount and a currency code or digital token identifier.

2. The currency code must always be a valid [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code or a valid [ISO 24165](https://www.iso.org/standard/80601.html) digital token identifier. [Current](https://www.currency-iso.org/en/home/tables/table-a1.html) and [historical](https://www.currency-iso.org/en/home/tables/table-a3.html) currency codes can be used.  See the [ISO Currency](https://www.currency-iso.org/en/home/tables.html) for more information. You can also identify the relevant codes by:

   * `Money.known_currencies/0` returns all the ISO 4217 currency codes known to `Money`
   * `Money.known_current_currencies/0` returns the ISO 4217 currency codes currently in use
   * `Money.known_historic_currencies/0` returns the list of historic ISO 4217 currency codes
   * `Money.known_tender_currencies/0` returns the list of ISO 4217 currencies known to be legal tender
   * `DigitalToken.tokens/0` returns a map of the known ISO 24165 digital tokens.

3. Money arithmetic can only be performed when both operands are of the same currency.

4. Money amounts are represented as a `Decimal`.

5. Money can be serialised to the database as a composite Postgres type that includes both the amount and the currency. For MySQL, money is serialized into a json column with the amount converted to a string to preserve precision since json does not have a decimal type. Serialization is entirely optional.

6. All arithmetic functions work on a `Decimal`. No rounding occurs automatically (unless expressly called out for a function, as is the case for `Money.split/2`).

7. Explicit rounding obeys the rounding rules for a given currency. The rounding rules are defined by the Unicode consortium in its CLDR repository as implemented by the hex package [localize](https://hex.pm/packages/localize). These rules define the number of fractional digits for a currency and the rounding increme