Money v0.8.1 Money View Source

Money implements a set of functions to store, retrieve and perform arithmetic on a %Money{} type that is composed of a currency code and a currency amount.

Money is very opinionated in the interests of serving as a dependable library that can underpin accounting and financial applications. In its initial release it can be expected that this contract may not be fully met.

How is this opinion expressed:

Money must always have both a amount and a currency code.
The currency code must always be valid.
Money arithmetic can only be performed when both operands are of the same currency.
Money amounts are represented as a Decimal.
Money is serialised to the database as a custom Postgres composite type that includes both the amount and the currency. Therefore for Ecto serialization Postgres is assumed as the data store. Serialization is entirely optional and Ecto is not a package dependency.
All arithmetic functions work in fixed point decimal. No rounding occurs automatically (unless expressly called out for a function).
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 ex_cldr. These rules define the number of fractional digits for a currency and the rounding increment where appropriate.

Link to this section Summary

Types

currency_code()

t()

Money is composed of an atom representation of an ISO4217 currency code and a Decimal representation of an amount

Functions

add(money1, money2)

Add two Money values

add!(a, b)

Add two Money values and raise on error

cmp(money1, money2)

Compares two Money values numerically. If the first number is greater than the second :gt is returned, if less than :lt is returned, if both numbers are equal :eq is returned

cmp!(money_1, money_2)

Compares two Money values numerically and raises on error

compare(money1, money2)

Compares two Money values numerically. If the first number is greater than the second #Integer<1> is returned, if less than Integer<-1> is returned. Otherwise, if both numbers are equal Integer<0> is returned

compare!(money_1, money_2)

Compares two Money values numerically and raises on error

div(money, number)

Divide a Money value by a number

div!(money, number)

Divide a Money value by a number and raise on error

equal?(arg1, arg2)

Returns a boolean indicating if two Money values are equal

from_tuple(arg)

Returns a %Money{} struct from a tuple consistenting of a currency code and a currency amount. The format of the argument is a 2-tuple where

from_tuple!(arg)

Returns a %Money{} struct from a tuple consistenting of a currency code and a currency amount. Raises an exception if the currency code is invalid

get_env(key, default, atom)

mult(money, number)

Multiply a Money value by a number

mult!(money, number)

Multiply a Money value by a number and raise on error

new(currency_code, amount)

Returns a %Money{} struct from a currency code and a currency amount or an error tuple of the form {:error, {exception, message}}

new!(currency_code, amount)

Returns a %Money{} struct from a currency code and a currency amount. Raises an exception if the current code is invalid

reduce(money)

Calls Decimal.reduce/1 on the given %Money{}

round(money, opts \\ [])

Round a Money value into the acceptable range for the defined currency

split(money, parts)

Split a Money value into a number of parts maintaining the currency’s precision and rounding and ensuring that the parts sum to the original amount

sub(money1, money2)

Subtract one Money value struct from another

sub!(a, b)

Subtract one Money value struct from another and raise on error

to_currency(money, to_currency, rates \\ Money.ExchangeRates.latest_rates())

Convert money from one currency to another

to_currency!(money, currency)

Convert money from one currency to another and raises on error

to_currency!(money, currency, rates)

to_decimal(money)

Returns the amount part of a Money type as a Decimal

to_string(money, options \\ [])

Returns a formatted string representation of a Money{}

to_string!(money, options \\ [])

Returns a formatted string representation of a Money{} or raises if there is an error

validate_currency_code(currency_code)

Link to this section Types

currency_code()

currency_code() :: atom()

t()

t() :: %Money{amount: Decimal.t(), currency: atom()}

Money is composed of an atom representation of an ISO4217 currency code and a Decimal representation of an amount.

Link to this section Functions

add(money1, money2)

add(Money.t(), Money.t()) :: Money.t()

Add two Money values.

Example

iex> Money.add Money.new(:USD, 200), Money.new(:USD, 100)
{:ok, Money.new(:USD, 300)}

iex> Money.add Money.new(:USD, 200), Money.new(:AUD, 100)
{:error, {ArgumentError, "Cannot add monies with different currencies. " <>
  "Received :USD and :AUD."}}

add!(a, b)

Add two Money values and raise on error.

Examples

iex> Money.add! Money.new(:USD, 200), Money.new(:USD, 100)
#Money<:USD, 300>

Money.add! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot add two %Money{} with different currencies. Received :USD and :CAD.

cmp(money1, money2)

cmp(Money.t(), Money.t()) ::
  :gt |
  :eq |
  :lt |
  {:error, {Exception.t(), String.t()}}

Compares two Money values numerically. If the first number is greater than the second :gt is returned, if less than :lt is returned, if both numbers are equal :eq is returned.

Examples

iex> Money.cmp Money.new(:USD, 200), Money.new(:USD, 100)
:gt

iex> Money.cmp Money.new(:USD, 200), Money.new(:USD, 200)
:eq

iex> Money.cmp Money.new(:USD, 200), Money.new(:USD, 500)
:lt

iex> Money.cmp Money.new(:USD, 200), Money.new(:CAD, 500)
{:error,
 {ArgumentError,
  "Cannot compare monies with different currencies. Received :USD and :CAD."}}

cmp!(money_1, money_2)

Compares two Money values numerically and raises on error.

Examples

Money.cmp! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot compare monies with different currencies. Received :USD and :CAD.

compare(money1, money2)

compare(Money.t(), Money.t()) ::
  -1 |
  0 |
  1 |
  {:error, {Exception.t(), String.t()}}

Examples

iex> Money.compare Money.new(:USD, 200), Money.new(:USD, 100)
1

iex> Money.compare Money.new(:USD, 200), Money.new(:USD, 200)
0

iex> Money.compare Money.new(:USD, 200), Money.new(:USD, 500)
-1

iex> Money.compare Money.new(:USD, 200), Money.new(:CAD, 500)
{:error,
 {ArgumentError,
  "Cannot compare monies with different currencies. Received :USD and :CAD."}}

compare!(money_1, money_2)

Compares two Money values numerically and raises on error.

Examples

Money.compare! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot compare monies with different currencies. Received :USD and :CAD.

div(money, number)

div(Money.t(), Cldr.Math.number_or_decimal()) :: Money.t()

Divide a Money value by a number.

money is a %Money{} struct
number is an integer or float

Note that dividing one %Money{} by another is not supported.

Example

iex> Money.div Money.new(:USD, 200), 2
{:ok, Money.new(:USD, 100)}

iex> Money.div(Money.new(:USD, 200), "xx")
{:error, {ArgumentError, "Cannot divide money by \"xx\""}}

div!(money, number)

Divide a Money value by a number and raise on error.

Examples

iex> Money.div Money.new(:USD, 200), 2
{:ok, Money.new(:USD, 100)}

Money.div(Money.new(:USD, 200), "xx")
** (ArgumentError) "Cannot divide money by \"xx\""]}}

equal?(arg1, arg2)

equal?(Money.t(), Money.t()) :: boolean()

Returns a boolean indicating if two Money values are equal

Example

iex> Money.equal? Money.new(:USD, 200), Money.new(:USD, 200)
true

iex> Money.equal? Money.new(:USD, 200), Money.new(:USD, 100)
false

from_tuple(arg)

from_tuple({binary(), number()}) :: Money.t()

Returns a %Money{} struct from a tuple consistenting of a currency code and a currency amount. The format of the argument is a 2-tuple where:

currency_code is an ISO4217 three-character upcased binary
amount is an integer, float or Decimal

This function is typically called from Ecto when it’s loading a %Money{} struct from the database.

Example

iex> Money.from_tuple({"USD", 100})
#Money<:USD, 100>

iex> Money.from_tuple({100, "USD"})
#Money<:USD, 100>

from_tuple!(arg)

Returns a %Money{} struct from a tuple consistenting of a currency code and a currency amount. Raises an exception if the currency code is invalid.

currency_code is an ISO4217 three-character upcased binary
amount is an integer, float or Decimal

This function is typically called from Ecto when it’s loading a %Money{} struct from the database.

Example

iex> Money.from_tuple!({"USD", 100})
#Money<:USD, 100>

Money.from_tuple!({"NO!", 100})
** (Money.UnknownCurrencyError) Currency "NO!" is not known
    (ex_money) lib/money.ex:130: Money.new!/1

get_env(key, default, atom)

mult(money, number)

mult(Money.t(), Cldr.Math.number_or_decimal()) :: Money.t()

Multiply a Money value by a number.

money is a %Money{} struct
number is an integer or float

Note that multipling one %Money{} by another is not supported.

Returns either {:ok, money} or {:error, reason}.

Example

iex> Money.mult(Money.new(:USD, 200), 2)
{:ok, Money.new(:USD, 400)}

iex> Money.mult(Money.new(:USD, 200), "xx")
{:error, {ArgumentError, "Cannot multiply money by \"xx\""}}

mult!(money, number)

Multiply a Money value by a number and raise on error.

Examples

iex> Money.mult!(Money.new(:USD, 200), 2)
#Money<:USD, 400>

Money.mult!(Money.new(:USD, 200), :invalid)
** (ArgumentError) Cannot multiply money by :invalid

new(currency_code, amount)

new(number(), binary()) :: Money.t()

Returns a %Money{} struct from a currency code and a currency amount or an error tuple of the form {:error, {exception, message}}.

currency_code is an ISO4217 three-character upcased binary or atom
amount is an integer, float or Decimal

Note that the currency_code and amount arguments can be supplied in either order,

Examples

iex> Money.new(:USD, 100)
#Money<:USD, 100>

iex> Money.new(100, :USD)
#Money<:USD, 100>

iex> Money.new("USD", 100)
#Money<:USD, 100>

iex> Money.new("thb", 500)
#Money<:THB, 500>

iex> Money.new(500, "thb")
#Money<:THB, 500>

iex> Money.new("EUR", Decimal.new(100))
#Money<:EUR, 100>

iex> Money.new(:XYZZ, 100)
{:error, {Money.UnknownCurrencyError, "Currency :XYZZ is not known"}}

new!(currency_code, amount)

Returns a %Money{} struct from a currency code and a currency amount. Raises an exception if the current code is invalid.

currency_code is an ISO4217 three-character upcased binary or atom
amount is an integer, float or Decimal

Examples

Money.new!(:XYZZ, 100)
** (Money.UnknownCurrencyError) Currency :XYZZ is not known
  (ex_money) lib/money.ex:177: Money.new!/2

reduce(money)

reduce(Money.t()) :: Money.t()

Calls Decimal.reduce/1 on the given %Money{}

This will reduce the coefficient and exponent of the decimal amount in a standard way that may aid in native comparison of %Money{} items.

Example

iex> x = %Money{currency: :USD, amount: %Decimal{sign: 1, coef: 42, exp: 0}}
#Money<:USD, 42>
iex> y = %Money{currency: :USD, amount: %Decimal{sign: 1, coef: 4200000000, exp: -8}}
#Money<:USD, 42.00000000>
iex> x == y
false
iex> y = Money.reduce(x)
#Money<:USD, 42>
iex> x == y
true

round(money, opts \\ [])

round(Money.t(), Keyword.t()) :: Money.t()

Round a Money value into the acceptable range for the defined currency.

money is a %Money{} struct
opts is a keyword list with the following keys:
- :rounding_mode that defines how the number will be rounded. See Decimal.Context. The default is :half_even which is also known as “banker’s rounding”
- :cash which determines whether the rounding is being applied to an accounting amount or a cash amount. Some currencies, such as the :AUD and :CHF have a cash unit increment minimum which requires a different rounding increment to an arbitrary accounting amount. The default is false.

There are two kinds of rounding applied:

Round to the appropriate number of fractional digits
Apply an appropriate rounding increment. Most currencies round to the same precision as the number of decimal digits, but some such as :AUD and :CHF round to a minimum such as 0.05 when its a cash amount.

Examples

iex> Money.round Money.new(123.7456, :CHF), cash: true
#Money<:CHF, 125>

iex> Money.round Money.new(123.7456, :CHF)
#Money<:CHF, 123.75>

Money.round Money.new(123.7456, :JPY)
#Money<:JPY, 124>

split(money, parts)

split(Money.t(), non_neg_integer()) :: {Money.t(), Money.t()}

Split a Money value into a number of parts maintaining the currency’s precision and rounding and ensuring that the parts sum to the original amount.

money is a %Money{} struct
parts is an integer number of parts into which the money is split

Returns a tuple {dividend, remainder} as the function result derived as follows:

Round the money amount to the required currency precision using Money.round/1
Divide the result of step 1 by the integer divisor
Round the result of the division to the precision of the currency using Money.round/1
Return two numbers: the result of the division and any remainder that could not be applied given the precision of the currency.

Examples

Money.split Money.new(123.5, :JPY), 3
{¥41, ¥1}

Money.split Money.new(123.4, :JPY), 3
{¥41, ¥0}

Money.split Money.new(123.7, :USD), 9
{$13.74, $0.04}

sub(money1, money2)

sub(Money.t(), Money.t()) ::
  {:ok, Money.t()} |
  {:error, {Exception.t(), String.t()}}

Subtract one Money value struct from another.

Returns either {:ok, money} or {:error, reason}.

Example

iex> Money.sub Money.new(:USD, 200), Money.new(:USD, 100)
{:ok, Money.new(:USD, 100)}

sub!(a, b)

Subtract one Money value struct from another and raise on error.

Returns either {:ok, money} or {:error, reason}.

Examaples

iex> Money.sub! Money.new(:USD, 200), Money.new(:USD, 100)
#Money<:USD, 100>

Money.sub! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot subtract monies with different currencies. Received :USD and :CAD.

to_currency(money, to_currency, rates \\ Money.ExchangeRates.latest_rates())

to_currency(Money.t(), Money.currency_code(), Map.t()) ::
  {:ok, Map.t()} |
  {:error, {Exception.t(), String.t()}}

Convert money from one currency to another.

money is a %Money{} struct
to_currency is a valid currency code into which the money is converted
rates is a Map of currency rates where the map key is an upcased atom or string and the value is a Decimal conversion factor. The default is the latest available exchange rates returned from Money.ExchangeRates.latest_rates()

Examples

Money.to_currency(Money.new(:USD, 100), :AUD, %{USD: Decimal.new(1), AUD: Decimal.new(0.7345)})
{:ok, #Money<:AUD, 73.4500>}

Money.to_currency(Money.new("USD", 100), "AUD", %{"USD" => Decimal.new(1), "AUD" => Decimal.new(0.7345)})
{:ok, #Money<:AUD, 73.4500>}

iex> Money.to_currency Money.new(:USD, 100) , :AUDD, %{USD: Decimal.new(1), AUD: Decimal.new(0.7345)}
{:error, {Cldr.UnknownCurrencyError, "Currency :AUDD is not known"}}

iex> Money.to_currency Money.new(:USD, 100) , :CHF, %{USD: Decimal.new(1), AUD: Decimal.new(0.7345)}
{:error, {Money.ExchangeRateError, "No exchange rate is available for currency :CHF"}}

to_currency!(money, currency)

Convert money from one currency to another and raises on error

Examples

iex> Money.to_currency! Money.new(:USD, 100) , :AUD, %{USD: Decimal.new(1), AUD: Decimal.new(0.7345)}
#Money<:AUD, 73.4500>

iex> Money.to_currency! Money.new("USD", 100) , "AUD", %{"USD" => Decimal.new(1), "AUD" => Decimal.new(0.7345)}
#Money<:AUD, 73.4500>

Money.to_currency! Money.new(:USD, 100) , :ZZZ, %{USD: Decimal.new(1), AUD: Decimal.new(0.7345)}
** (Cldr.UnknownCurrencyError) Currency :ZZZ is not known

to_currency!(money, currency, rates)

to_decimal(money)

to_decimal(Money.t()) :: Decimal.t()

Returns the amount part of a Money type as a Decimal

Example

iex> m = Money.new("USD", 100)
iex> Money.to_decimal(m)
#Decimal<100>

to_string(money, options \\ [])

Returns a formatted string representation of a Money{}.

Formatting is performed according to the rules defined by CLDR. See Cldr.Number.to_string/2 for formatting options. The default is to format as a currency which applies the appropriate rounding and fractional digits for the currency.

Examples

iex> Money.to_string Money.new(:USD, 1234)
{:ok, "$1,234.00"}

iex> Money.to_string Money.new(:JPY, 1234)
{:ok, "¥1,234"}

iex> Money.to_string Money.new(:THB, 1234)
{:ok, "THB1,234.00"}

iex> Money.to_string Money.new(:USD, 1234), format: :long
{:ok, "1,234 US dollars"}

to_string!(money, options \\ [])

Returns a formatted string representation of a Money{} or raises if there is an error.

Formatting is performed according to the rules defined by CLDR. See Cldr.Number.to_string!/2 for formatting options. The default is to format as a currency which applies the appropriate rounding and fractional digits for the currency.

Examples

iex> Money.to_string! Money.new(:USD, 1234)
"$1,234.00"

iex> Money.to_string! Money.new(:JPY, 1234)
"¥1,234"

iex> Money.to_string! Money.new(:THB, 1234)
"THB1,234.00"

iex> Money.to_string! Money.new(:USD, 1234), format: :long
"1,234 US dollars"

validate_currency_code(currency_code)