Money (Money v5.4.0) View Source

Money implements a set of functions to store, retrieve, convert and perform arithmetic on a Money.t type that is composed of a currency code and a decimal currency amount.

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

This opinion expressed by ensuring that:

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

amount()

currency_code()

t()

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

Functions

abs(money)

The absolute value of a Money amount. Returns a Money type with a positive sign for the amount.

add(money1, money2)

Add two Money values.

add!(money_1, money_2)

Add two Money values and raise on error.

cmp(money_1, money_2)

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.

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 :gt is returned, if less than :lt is returned, if both numbers are equal :eq is returned.

compare!(money_1, money_2)

Compares two Money values numerically and raises on error.

cross_rate(from, to, rates \\ Money.ExchangeRates.latest_rates())

Returns the effective cross-rate to convert from one currency to another.

cross_rate!(from, to_currency, rates \\ Money.ExchangeRates.latest_rates())

Returns the effective cross-rate to convert from one currency to another.

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_float(currency_code, amount)

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

from_float!(currency_code, amount)

Returns a %Money{} struct from a currency code and a float amount, or raises an exception if the currency code is invalid.

from_integer(amount, currency)

Convert an integer representation of money into a Money struct.

get_env(key, default, atom)

known_currencies()

See Cldr.known_currencies/0.

known_current_currencies()

See Money.Currency.known_current_currencies/0.

known_historic_currencies()

See Money.Currency.known_historic_currencies/0.

known_tender_currencies()

See Money.Currency.known_tender_currencies/0.

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, options \\ [])

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, options \\ [])

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

normalize(money)

Normalizes the underlying decimal amount in a given Money.t()

parse(string, options \\ [])

Parse a string and return a Money.t or an error.

put_fraction(money, fraction \\ 0)

Set the fractional part of a Money.

reduce(money) deprecated

round(money, opts \\ [])

Round a Money value into the acceptable range for the requested 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.

sum(money_list, rates \\ %{})

Sum a list of monies that may be in different currencies.

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

Convert money from one currency to another.

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

Convert money from one currency to another and raises on error

to_decimal(money)

Returns the amount part of a Money type as a Decimal

to_integer_exp(money, opts \\ [])

Returns a tuple comprising the currency code, integer amount, exponent and remainder

to_string(money, options \\ [])

Returns a formatted string representation of a Money{}.

to_string!(money, options \\ [])

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

validate_currency(currency_code)

See Cldr.validate_currency/1.

zero(currency)

Return a zero amount Money.t in the given currency

Link to this section Types

amount()

Specs

amount() :: float() | integer() | Decimal.t() | String.t()

currency_code()

Specs

currency_code() :: atom() | String.t()

t()

Specs

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

abs(money)

Specs

abs(money :: t()) :: t()

The absolute value of a Money amount. Returns a Money type with a positive sign for the amount.

Arguments

money is any valid Money.t type returned by Money.new/2

Returns

a Money.t

Example

iex> m = Money.new("USD", -100)
iex> Money.abs(m)
#Money<:USD, 100>

add(money1, money2)

Specs

add(money_1 :: t(), money_2 :: t()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Add two Money values.

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

{:ok, money} or
{:error, reason}

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!(money_1, money_2)

Add two Money values and raise on error.

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

{:ok, money} or
raises an exception

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(money_1, money_2)

Specs

cmp(money_1 :: t(), money_2 :: t()) ::
  -1 | 0 | 1 | {:error, {module(), String.t()}}

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

-1 | 0 | 1 or
{:error, {module(), String.t}}

Examples

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

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

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

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.

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

-1 | 0 | 1 or
raises an exception

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)

Specs

compare(money_1 :: t(), money_2 :: t()) ::
  :gt | :eq | :lt | {:error, {module(), 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.

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

:gt | :eq | :lt or
{:error, {module(), String.t}}

Examples

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

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

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

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.

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

:gt | :eq | :lt or
raises an exception

Examples

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

cross_rate(from, to, rates \\ Money.ExchangeRates.latest_rates())

Specs

cross_rate(
  t() | currency_code(),
  currency_code(),
  Money.ExchangeRates.t() | {:ok, Money.ExchangeRates.t()}
) :: {:ok, Decimal.t()} | {:error, {module(), String.t()}}

Returns the effective cross-rate to convert from one currency to another.

Arguments

from is any Money.t struct returned by Cldr.Currency.new/2 or a valid currency code
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.cross_rate(Money.new(:USD, 100), :AUD, %{USD: Decimal.new(1), AUD: Decimal.new("0.7345")})
{:ok, #Decimal<0.7345>}

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

cross_rate!(from, to_currency, rates \\ Money.ExchangeRates.latest_rates())

Specs

cross_rate!(
  t() | currency_code(),
  currency_code(),
  Money.ExchangeRates.t() | {:ok, Money.ExchangeRates.t()}
) :: Decimal.t() | no_return()

Returns the effective cross-rate to convert from one currency to another.

Arguments

from is any Money.t struct returned by Cldr.Currency.new/2 or a valid currency code
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

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

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

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

div(money, number)

Specs

div(t(), Cldr.Math.number_or_decimal()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Divide a Money value by a number.

Arguments

money is any valid Money.t types returned by Money.new/2
number is an integer, float or Decimal.t

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

Returns

{:ok, money} or
{:error, reason}

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.

Arguments

money is any valid Money.t types returned by Money.new/2
number is an integer, float or Decimal.t

Returns

a Money.t struct or
raises an exception

Examples

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

iex> Money.div!(Money.new(:USD, 200), "xx")
** (ArgumentError) Cannot divide money by "xx"

equal?(arg1, arg2)

Specs

equal?(money_1 :: t(), money_2 :: t()) :: boolean()

Returns a boolean indicating if two Money values are equal

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

true or false

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_float(currency_code, amount)

(since 2.0.0)

Specs

from_float(float() | currency_code(), float() | currency_code()) ::
  t() | {:error, {module(), String.t()}}

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

Floats are fraught with danger in computer arithmetic due to the unexpected loss of precision during rounding. The IEEE754 standard indicates that a number with a precision of 16 digits should round-trip convert without loss of fidelity. This function supports numbers with a precision up to 15 digits and will error if the provided amount is outside that range.

Note that Money cannot detect lack of precision or rounding errors introduced upstream. This function therefore should be used with great care and its use should be considered potentially harmful.

Arguments

currency_code is an ISO4217 three-character upcased binary or atom
amount is a float

Examples

iex> Money.from_float 1.23456, :USD
#Money<:USD, 1.23456>

iex> Money.from_float 1.234567890987656, :USD
{:error,
  {Money.InvalidAmountError,
    "The precision of the float 1.234567890987656 is " <>
    "greater than 15 which could lead to unexpected results. " <>
    "Reduce the precision or call Money.new/2 with a Decimal or String amount"}}

from_float!(currency_code, amount)

(since 2.0.0)

Specs

from_float!(currency_code(), float()) :: t() | no_return()

Returns a %Money{} struct from a currency code and a float amount, or raises an exception if the currency code is invalid.

See Money.from_float/2 for further information.

Arguments

currency_code is an ISO4217 three-character upcased binary or atom
amount is a float

Examples

iex> Money.from_float!(:USD, 1.234)
#Money<:USD, 1.234>

Money.from_float!(:USD, 1.234567890987654)
#=> ** (Money.InvalidAmountError) The precision of the float 1.234567890987654 is greater than 15 which could lead to unexpected results. Reduce the precision or call Money.new/2 with a Decimal or String amount
    (ex_money) lib/money.ex:293: Money.from_float!/2

from_integer(amount, currency)

Specs

from_integer(integer(), currency_code()) :: t() | {:error, module(), String.t()}

Convert an integer representation of money into a Money struct.

This is the inverse operation of Money.to_integer_exp/1. Note that the ISO definition of currency digits (subunit) is always used. This is, in some cases like the Colombian Peso (COP) different to the CLDR definition.

Options

integer is an integer representation of a mooney item including any decimal digits. ie. 20000 would interpreted to mean $200.00
currency is the currency code for the integer. The assumed decimal places is derived from the currency code.

Returns

A Money struct or
{:error, {Cldr.UnknownCurrencyError, message}}

Examples

iex> Money.from_integer(20000, :USD)
#Money<:USD, 200.00>

iex> Money.from_integer(200, :JPY)
#Money<:JPY, 200>

iex> Money.from_integer(20012, :USD)
#Money<:USD, 200.12>

iex> Money.from_integer(20012, :COP)
#Money<:COP, 200.12>

get_env(key, default, atom)

known_currencies()

See Cldr.known_currencies/0.

known_current_currencies()

See Money.Currency.known_current_currencies/0.

known_historic_currencies()

See Money.Currency.known_historic_currencies/0.

known_tender_currencies()

See Money.Currency.known_tender_currencies/0.

mult(money, number)

Specs

mult(t(), Cldr.Math.number_or_decimal()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Multiply a Money value by a number.

Arguments

money is any valid Money.t type returned by Money.new/2
number is an integer, float or Decimal.t

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

Returns

{: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)

Specs

mult!(t(), Cldr.Math.number_or_decimal()) :: t() | none()

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

Arguments

money is any valid Money.t types returned by Money.new/2
number is an integer, float or Decimal.t

Returns

a Money.t or
raises an exception

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, options \\ [])

Specs

new(amount() | currency_code(), amount() | currency_code(), Keyword.t()) ::
  t() | {:error, {module(), String.t()}}

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

Arguments

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

Options

:locale is any known locale. The locale is used to normalize any binary (String) amounts to a form that can be consumed by Decimal.new/1. This consists of removing any localised grouping characters and replacing the localised decimal separator with a ".".

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("EUR", Decimal.new(100))
#Money<:EUR, 100>

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

iex> Money.new(:XYZZ, 100)
{:error, {Money.UnknownCurrencyError, "The currency :XYZZ is invalid"}}

iex> Money.new("1.000,99", :EUR, locale: "de")
#Money<:EUR, 1000.99>

iex> Money.new 123.445, :USD
{:error,
 {Money.InvalidAmountError,
  "Float amounts are not supported in new/2 due to potenial " <>
  "rounding and precision issues.  If absolutely required, " <>
  "use Money.from_float/2"}}

new!(currency_code, amount, options \\ [])

Specs

new!(amount() | currency_code(), amount() | currency_code(), Keyword.t()) ::
  t() | no_return()

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

Arguments

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

normalize(money)

(since 5.0.0)

Specs

normalize(t()) :: t()

Normalizes the underlying decimal amount in a given Money.t()

This will normalize the coefficient and exponent of the decimal amount in a standard way that may aid in native comparison of %Money.t() 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.normalize(x)
#Money<:USD, 42>
iex> x == y
true

parse(string, options \\ [])

(since 3.2.0)

Specs

parse(String.t(), Keyword.t()) :: t() | {:error, {module(), String.t()}}

Parse a string and return a Money.t or an error.

The string to be parsed is required to have a currency code and an amount. The currency code may be placed before the amount or after, but not both.

Parsing is strict. Additional text surrounding the currency code and amount will cause the parse to fail.

Arguments

string is a string to be parsed
options is a keyword list of options that is passed to Money.new/3 with the exception of the options listed below

Options

:backend is any module() that includes use Cldr and therefore is a Cldr backend module(). The default is Money.default_backend()
:locale is any valid locale returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2 The default is <backend>.get_locale()
:only is an atom or list of atoms representing the currencies or currency types to be considered for a match. The equates to a list of acceptable currencies for parsing. See the notes below for currency types.
:except is an atom or list of atoms representing the currencies or currency types to be not considered for a match. This equates to a list of unacceptable currencies for parsing. See the notes below for currency types.
:fuzzy is a float greater than 0.0 and less than or equal to 1.0 which is used as input to the String.jaro_distance/2 to determine is the provided currency string is close enough to a known currency string for it to identify definitively a currency code. It is recommended to use numbers greater than 0.8 in order to reduce false positives.
:default_currency is any valid currency code or false that will used if no currency code, symbol or description is indentified in the parsed string. The default is nil which means that the default currency associated with the :locale option will be used. If false then the currency assocated with the :locale option will not be used and an error will be returned if there is no currency in the string being parsed.

Returns

a Money.t if parsing is successful or
{:error, {exception, reason}} if an error is detected.

Notes

The :only and :except options accept a list of currency codes and/or currency types. The following types are recognised.

If both :only and :except are specified, the :except entries take priority - that means any entries in :except are removed from the :only entries.

:all, the default, considers all currencies
:current considers those currencies that have a :to date of nil and which also is a known ISO4217 currency
:historic is the opposite of :current
:tender considers currencies that are legal tender
:unannotated considers currencies that don't have "(some string)" in their names. These are usually financial instruments.

Examples

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

iex> Money.parse "USD 100,00", locale: "de"
#Money<:USD, 100.00>

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

iex> Money.parse("100 eurosports", fuzzy: 0.8)
#Money<:EUR, 100>

iex> Money.parse("100", default_currency: :EUR)
#Money<:EUR, 100>

iex> Money.parse("100 eurosports", fuzzy: 0.9)
{:error, {Money.UnknownCurrencyError, "The currency \"eurosports\" is unknown or not supported"}}

iex> Money.parse("100 afghan afghanis")
#Money<:AFN, 100>

iex> Money.parse("100", default_currency: false)
{:error, {Money.Invalid,
  "A currency code, symbol or description must be specified but was not found in \"100\""}}

iex> Money.parse("USD 100 with trailing text")
{:error, {Money.ParseError, "Could not parse \"USD 100 with trailing text\"."}}

put_fraction(money, fraction \\ 0)

Set the fractional part of a Money.

Arguments

money is a %Money{} struct
fraction is an integer amount that will be set as the fraction of the money

Notes

The fraction can only be set if it matches the number of decimal digits for the currency associated with the money. Therefore, for a currency with 2 decimal digits, the maximum for fraction is 99.

Examples

iex> Money.put_fraction Money.new(:USD, "2.49"), 99
#Money<:USD, 2.99>

iex> Money.put_fraction Money.new(:USD, "2.49"), 0
#Money<:USD, 2.0>

iex> Money.put_fraction Money.new(:USD, "2.49"), 999
{:error,
 {Money.InvalidAmountError, "Rounding up to 999 is invalid for currency :USD"}}

reduce(money)

This function is deprecated. Use Money.normalize/1 instead..

round(money, opts \\ [])

Specs

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

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

Arguments

money is a %Money{} struct
opts is a keyword list of options

Options

: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"
:currency_digits which determines the rounding increment. The valid options are :cash, :accounting and :iso or an integer value representing the rounding factor. The default is :iso.

Notes

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 :CHF round to a minimum such as 0.05 when its a cash amount. The rounding increment is applied when the option :currency_digits is set to :cash

Examples

iex> Money.round Money.new("123.73", :CHF), currency_digits: :cash
#Money<:CHF, 123.75>

iex> Money.round Money.new("123.73", :CHF), currency_digits: 0
#Money<:CHF, 124>

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

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

split(money, parts)

Specs

split(t(), non_neg_integer()) :: {t(), 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.

Arguments

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)

Specs

sub(money_1 :: t(), money_2 :: t()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Subtract one Money value struct from another.

Options

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

{: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)

Specs

sub!(money_1 :: t(), money_2 :: t()) :: t() | none()

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

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

Arguments

money_1 and money_2 are any valid Money.t types returned by Money.new/2

Returns

a Money.t struct or
raises an exception

Examples

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.

sum(money_list, rates \\ %{})

(since 5.3.0)

Specs

sum([t(), ...], Money.ExchangeRates.t()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Sum a list of monies that may be in different currencies.

Arguments

money_list is a list of any valid Money.t types returned by Money.new/2
rates is a map of exchange rates. The default is %{}. Money.ExchangeRates.latest_rates/0 can be used to return the latest known exchange rates which can then applied as the rates parameter.

Returns

{:ok, money} representing the sum of the maybe converted money amounts. The currency of the sum is the currency of the first Money in the money_list.
{:error, {exception, reason}} describing an error.

Examples

iex> Money.sum [Money.new(:USD, 100), Money.new(:USD, 200), Money.new(:USD, 50)]
{:ok, Money.new(:USD, 350)}

iex> Money.sum [Money.new(:USD, 100), Money.new(:USD, 200), Money.new(:AUD, 50)]
{:error,
 {Money.ExchangeRateError, "No exchange rate is available for currency :AUD"}}

iex> rates = %{AUD: Decimal.new(2), USD: Decimal.new(1)}
iex> Money.sum [Money.new(:USD, 100), Money.new(:USD, 200), Money.new(:AUD, 50)], rates
{:ok, Money.from_float(:USD, 325.0)}

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

Specs

to_currency(
  t(),
  currency_code(),
  Money.ExchangeRates.t()
  | {:ok, Money.ExchangeRates.t()}
  | {:error, {module(), String.t()}}
) :: {:ok, t()} | {:error, {module(), String.t()}}

Convert money from one currency to another.

Arguments

money is any Money.t struct returned by Cldr.Currency.new/2
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()

Converting to a currency defined in a locale

To convert a Money to a currency defined by a locale, Cldr.Currency.currency_from_locale/1 can be called with a t:Cldr.LanguageTag.t() parameter. It will return the currency configured for that locale.

Examples

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

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

iex> Money.to_currency(Money.new(:USD, 100), :AUDD,
...>   %{USD: Decimal.new(1), AUD: Decimal.from_float(0.7345)})
{:error, {Cldr.UnknownCurrencyError, "The currency :AUDD is invalid"}}

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

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

Specs

to_currency!(
  t(),
  currency_code(),
  Money.ExchangeRates.t()
  | {:ok, Money.ExchangeRates.t()}
  | {:error, {module(), String.t()}}
) :: t() | no_return()

Convert money from one currency to another and raises on error

Arguments

money is any t:Money.t() struct returned by Cldr.Currency.new/2
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

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

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

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

to_decimal(money)

Specs

to_decimal(money :: t()) :: Decimal.t()

Returns the amount part of a Money type as a Decimal

Arguments

money is any valid Money.t type returned by Money.new/2

Returns

a Decimal.t

Example

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

to_integer_exp(money, opts \\ [])

Returns a tuple comprising the currency code, integer amount, exponent and remainder

Some services require submission of money items as an integer with an implied exponent that is appropriate to the currency.

Rather than return only the integer, Money.to_integer_exp returns the currency code, integer, exponent and remainder. The remainder is included because to return an integer money with an implied exponent the Money has to be rounded potentially leaving a remainder.

Options

money is any Money.t struct returned by Cldr.Currency.new/2

Notes

Since the returned integer is expected to have the implied fractional digits the Money needs to be rounded which is what this function does.

Example

iex> m = Money.new(:USD, "200.012356")
#Money<:USD, 200.012356>
iex> Money.to_integer_exp(m)
{:USD, 20001, -2, Money.new(:USD, "0.002356")}

iex> m = Money.new(:USD, "200.00")
#Money<:USD, 200.00>
iex> Money.to_integer_exp(m)
{:USD, 20000, -2, Money.new(:USD, "0.00")}

to_string(money, options \\ [])

Specs

to_string(t(), Keyword.t() | Cldr.Number.Format.Options.t()) ::
  {:ok, String.t()} | {:error, {atom(), String.t()}}

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.

Arguments

money is any valid Money.t type returned by Money.new/2
options is a keyword list of options

Returns

{:ok, string} or
{:error, reason}

Options

:backend is any CLDR backend module. The default is Money.default_backend().
Any other options are passed to Cldr.Number.to_string/3

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, "THB 1,234.00"}

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

to_string!(money, options \\ [])

Specs

to_string!(t(), Keyword.t()) :: String.t() | no_return()

Returns a formatted string representation of a Money.t 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.

Arguments

money is any valid Money.t type returned by Money.new/2
options is a keyword list of options

Options

:backend is any CLDR backend module. The default is Money.default_backend().
Any other options are passed to Cldr.Number.to_string/3

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)
"THB 1,234.00"

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

validate_currency(currency_code)

See Cldr.validate_currency/1.

zero(currency)

Specs

zero(currency_code() | t()) :: t()

Return a zero amount Money.t in the given currency

Example

iex> Money.zero(:USD)
#Money<:USD, 0>

iex> money = Money.new(:USD, 200)
iex> Money.zero(money)
#Money<:USD, 0>

iex> Money.zero :ZZZ
{:error, {Cldr.UnknownCurrencyError, "The currency :ZZZ is invalid"}}