View Source Money (Money v5.17.0)
Money implements a set of functions to store, retrieve, convert and perform
arithmetic on a Money.t/0
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.
Summary
Types
An amount can be expressed as a float, an integer, a Decimal or a string (which is converted to a Decimal)
A currency code is an ISO 4217 code expressed as an atom or binary or an ISO 24165 Digital Token ID or Digital Token short name.
Functions
Add two Money
values.
Add two Money
values and raise on error.
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.
Compares two Money
values numerically and raises on error.
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.
Compares two Money
values numerically and raises on error.
Returns the effective cross-rate to convert from one currency to another.
Returns the effective cross-rate to convert from one currency to another.
Returns the default ex_cldr
backend configured
for Money
, if any. If no default backing is
configured, an exception is raised.
Divide a Money
value by a number.
Divide a Money
value by a number and raise on error.
Returns a boolean indicating if two Money
values are equal
Returns a %Money{} struct from a currency code and a float amount, or
an error tuple of the form {:error, {exception, message}}
.
Returns a %Money{} struct from a currency code and a float amount, or raises an exception if the currency code is invalid.
Convert an integer representation of money into a Money
struct.
Returns a boolean indicating if Money.t/0
is an integer value (has no significant fractional
digits).
Localizes a Money
by converting it to the currency
of the specified locale.
Multiply a Money
value by a number.
Multiply a Money
value by a number and raise on error.
Returns a boolean indicating if Money.t/0
has a negative value.
Returns a %Money{} struct from a currency code and a currency amount or
an error tuple of the form {:error, {exception, message}}
.
Returns a %Money{} struct from a currency code and a currency amount. Raises an exception if the current code is invalid.
Normalizes the underlying decimal amount in a
given Money.t/0
.
Parse a string and return a Money.t/0
or an error.
Returns a boolean indicating if Money.t/0
has a positive value.
Add format options to a Money.t/0
.
Set the fractional part of a Money
.
Round a Money
value into the acceptable range for the requested currency.
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.
Subtract one Money
value struct from another.
Subtract one Money
value struct from another and raise on error.
Sum a list of monies that may be in different currencies.
Convert money
from one currency to another.
Convert money
from one currency to another or raises on error.
Returns the currecny code of a Money
type
as an atom
.
Returns a tuple comprising the currency code, integer amount, exponent and remainder.
Returns a formatted string representation of a Money.t/0
.
Returns a formatted string representation of a Money.t/0
or raises if
there is an error.
Return a zero amount Money.t/0
in the given currency.
Returns a boolean indicating if Money.t/0
has a zero value.
Types
An amount can be expressed as a float, an integer, a Decimal or a string (which is converted to a Decimal)
A currency code is an ISO 4217 code expressed as an atom or binary or an ISO 24165 Digital Token ID or Digital Token short name.
@type t() :: %Money{ amount: Decimal.t(), currency: currency_code(), format_options: Keyword.t() }
Money is composed of an atom representation of an ISO4217 currency code and
a Decimal
representation of an amount.
Functions
The absolute value of a Money
amount.
Returns a Money.t/0
type with a positive sign for the amount.
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
.
Returns
- a
Money.t/0
.
Example
iex> m = Money.new("USD", -100)
iex> Money.abs(m)
Money.new(:USD, "100")
Add two Money
values.
Arguments
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.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 two Money
values and raise on error.
Arguments
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.new/2
Returns
a
Money.t/0
struct orraises an exception
Examples
iex> Money.add! Money.new(:USD, 200), Money.new(:USD, 100)
Money.new(:USD, "300")
Money.add! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot add two %Money{} with different currencies. Received :USD and :CAD.
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.
Arguments
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.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."}}
Compares two Money
values numerically and raises on error.
Arguments
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.new/2
Returns
-1
|0
|1
orraises an exception
Examples
Money.cmp! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot compare monies with different currencies. Received :USD and :CAD.
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
andmoney_2
are any validMoney.t/0
types returned byMoney.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."}}
Compares two Money
values numerically and raises on error.
Arguments
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.new/2
.
Returns
:gt
|:eq
|:lt
orraises an exception
Examples
Money.compare! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot compare monies with different currencies. Received :USD and :CAD.
@spec 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 anyMoney.t/0
struct returned byCldr.Currency.new/2
or a valid currency code.to_currency
is a valid currency code into which themoney
is converted.rates
is aMap
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 fromMoney.ExchangeRates.latest_rates/0
.
Examples
Money.cross_rate(Money.new(:USD, 100), :AUD, %{USD: Decimal.new(1), AUD: Decimal.new("0.7345")})
{:ok, Decimal.new("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())
View Source@spec 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 anyMoney.t/0
struct returned byCldr.Currency.new/2
or a valid currency code.to_currency
is a valid currency code into which themoney
is converted.rates
is aMap
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 fromMoney.ExchangeRates.latest_rates/0
.
Examples
iex> Money.cross_rate!(Money.new(:USD, 100), :AUD, %{USD: Decimal.new(1), AUD: Decimal.new("0.7345")})
Decimal.new("0.7345")
iex> Money.cross_rate!(:USD, :AUD, %{USD: Decimal.new(1), AUD: Decimal.new("0.7345")})
Decimal.new("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
Returns the default ex_cldr
backend configured
for Money
, if any. If no default backing is
configured, an exception is raised.
@spec div(t(), Cldr.Math.number_or_decimal()) :: {:ok, t()} | {:error, {module(), String.t()}}
Divide a Money
value by a number.
Arguments
money
is any validMoney.t/0
types returned byMoney.new/2
number
is an integer, float orDecimal.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\""}}
@spec div!(t(), Cldr.Math.number_or_decimal()) :: t() | none()
Divide a Money
value by a number and raise on error.
Arguments
money
is any validMoney.t/0
types returned byMoney.new/2
number
is an integer, float orDecimal.t
Returns
a
Money.t/0
struct orraises an exception
Examples
iex> Money.div!(Money.new(:USD, 200), 2)
Money.new(:USD, "100")
iex> Money.div!(Money.new(:USD, 200), "xx")
** (ArgumentError) Cannot divide money by "xx"
Returns a boolean indicating if two Money
values are equal
Arguments
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.new/2
Returns
true
orfalse
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
@spec from_float(float() | currency_code(), float() | currency_code(), Keyword.t()) :: 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 binary or atom currency code or an ISO 24165 token identifier or shortname.amount
is a floatoptions
is a keyword list of options passed toMoney.new/3
. The default is[]
.
Examples
iex> Money.from_float 1.23456, :USD
Money.new(: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"}}
@spec from_float!(currency_code(), float(), Keyword.t()) :: 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.
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 binary or atom currency code or an ISO 24165 token identifier or shortname.amount
is a floatoptions
is a keyword list of options passed toMoney.new/3
. The default is[]
.
Examples
iex> Money.from_float!(:USD, 1.234)
Money.new(: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
@spec from_integer(integer(), currency_code(), Keyword.t()) :: t() | {:error, {module(), String.t()}}
Convert an integer representation of money into a Money
struct.
Arguments
integer
is an integer representation of a money amount including any decimal digits. ie.20000
would be interpreted to mean$200.00
if thecurrency
is:USD
and no:fractional_digits
option was provided.currency
is the currency code for theinteger
. The assumed decimal precision is derived from the currency code if nofractional_digits
option is specified.options
is a keyword list of options.
Options
:fractional_digits
which determines the currency precision implied by theinteger
. The valid options are:cash
,:accounting
,:iso
or a non-negative integer. The default is:iso
which uses the ISO 4217 definition of currency digits.
All other options are passed to Money.new/3
.
Returns
A
Money.t/0
struct or{:error, {exception, message}}
Notes
Some currencies, like the Iraqi Dinar
have a difference in the decimal digits defined by CLDR versus
those defined by ISO 4217. CLDR
defines the decimal digits for IQD
as 0
whereas ISO 4217 defines
3
decimal digits.
Since converting an integer to a money amount is very
sensitive to the number of fractional digits specified it is
important to be very clear about the precision of the data used
with this function and care taken in specifying the :fractional_digits
parameter.
Examples
iex> Money.from_integer(20000, :USD)
Money.new(:USD, "200.00")
iex> Money.from_integer(200, :JPY)
Money.new(:JPY, "200")
iex> Money.from_integer(20012, :USD)
Money.new(:USD, "200.12")
iex> Money.from_integer(20012, :USD, fractional_digits: 3)
Money.new(:USD, "20.012")
iex> Money.from_integer(20012, :IQD)
Money.new(:IQD, "20.012")
Returns a boolean indicating if Money.t/0
is an integer value (has no significant fractional
digits).
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
Example
iex> Money.integer?(Money.new(:USD, 0))
true
iex> Money.integer?(Money.new(:USD, "1.10"))
false
Localizes a Money
by converting it to the currency
of the specified locale.
Arguments
money
is anyMoney.t/0
struct returned byCldr.Currency.new/2
.options
is a keyword list of options.
Options
:locale
is any valid locale returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
The default is<backend>.get_locale()
:backend
is any module() that includesuse Cldr
and therefore is aCldr
backend module(). The default isMoney.default_backend()
Returns
{:ok, localized_money}
or{:error, {exception, reason}}
@spec mult(t(), Cldr.Math.number_or_decimal()) :: {:ok, t()} | {:error, {module(), String.t()}}
Multiply a Money
value by a number.
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
number
is an integer, float orDecimal.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\""}}
@spec mult!(t(), Cldr.Math.number_or_decimal()) :: t() | none()
Multiply a Money
value by a number and raise on error.
Arguments
money
is any validMoney.t/0
types returned byMoney.new/2
number
is an integer, float orDecimal.t
Returns
a
Money.t/0
orraises an exception
Examples
iex> Money.mult!(Money.new(:USD, 200), 2)
Money.new(:USD, "400")
Money.mult!(Money.new(:USD, 200), :invalid)
** (ArgumentError) Cannot multiply money by :invalid
Returns a boolean indicating if Money.t/0
has a negative value.
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
Example
iex> Money.negative?(Money.new(:USD, -1))
true
iex> Money.negative?(Money.new(:USD, 0))
false
iex> Money.negative?(Money.new(:USD, 1))
false
@spec 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 binary or atom currency code or an ISO 24165 token identifier or shortname.amount
is an integer, string or Decimal money amount.options
is a keyword list of options.
Options
:locale
is any known locale. The locale is used to normalize any binary (String) amounts to a form that can be consumed byDecimal.new/1
. This consists of removing any localised grouping characters and replacing the localised decimal separator with a ".". The default isCldr.get_locale/0
.:backend
is any module() that includesuse Cldr
and therefore is aCldr
backend module(). The default isMoney.default_backend/0
.Any other options are considered as formatting options to be applied by default when calling
Money.to_string/2
.
Note that the currency_code
and amount
arguments can be supplied in
either order,
Examples
iex> Money.new(:USD, 100)
Money.new(:USD, "100")
iex> Money.new(100, :USD)
Money.new(:USD, "100")
iex> Money.new("USD", 100)
Money.new(:USD, "100")
iex> Money.new("thb", 500)
Money.new(:THB, "500")
iex> Money.new("EUR", Decimal.new(100))
Money.new(:EUR, "100")
iex> Money.new(:EUR, "100.30")
Money.new(:EUR, "100.30")
iex> Money.new(:EUR, "100.30", fractional_digits: 4)
Money.new(:EUR, "100.30", fractional_digits: 4)
iex> Money.new(:XYZZ, 100)
{:error, {Money.UnknownCurrencyError, "The currency :XYZZ is invalid"}}
iex> Money.new("1.000,99", :EUR, locale: "de")
Money.new(: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"}}
@spec 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 binary or atom currency code or an ISO 24165 token identifier or shortname.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
Normalizes the underlying decimal amount in a
given Money.t/0
.
This will normalize the coefficient and exponent of the
decimal amount in a standard way that may aid in
native comparison of Money.t/0
items.
Example
iex> x = %Money{currency: :USD, amount: %Decimal{sign: 1, coef: 42, exp: 0}}
Money.new(:USD, "42")
iex> y = %Money{currency: :USD, amount: %Decimal{sign: 1, coef: 4200000000, exp: -8}}
Money.new(:USD, "42.00000000")
iex> x == y
false
iex> y = Money.normalize(x)
Money.new(:USD, "42")
iex> x == y
true
Parse a string and return a Money.t/0
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 parsedoptions
is a keyword list of options that is passed toMoney.new/3
with the exception of the options listed below
Options
:backend
is any module() that includesuse Cldr
and therefore is aCldr
backend module(). The default isMoney.default_backend()
:locale
is any valid locale returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
The default is<backend>.get_locale()
:only
is anatom
or list ofatoms
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 anatom
or list ofatoms
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 than0.0
and less than or equal to1.0
which is used as input to theString.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 than0.8
in order to reduce false positives.:default_currency
is any valid currency code orfalse
that will used if no currency code, symbol or description is indentified in the parsed string. The default isnil
which means that the default currency associated with the:locale
option will be used. Iffalse
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/0
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.new(:USD, "100")
iex> Money.parse "USD 100,00", locale: "de"
Money.new(:USD, "100.00")
iex> Money.parse("100 USD")
Money.new(:USD, "100")
iex> Money.parse("100 eurosports", fuzzy: 0.8)
Money.new(:EUR, "100")
iex> Money.parse("100", default_currency: :EUR)
Money.new(: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.new(: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\"."}}
Returns a boolean indicating if Money.t/0
has a positive value.
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
Example
iex> Money.positive?(Money.new(:USD, 1))
true
iex> Money.positive?(Money.new(:USD, 0))
false
iex> Money.positive?(Money.new(:USD, -1))
false
Add format options to a Money.t/0
.
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
options
is a keyword list of options. These options are used when callingMoney.to_string/2
. The default is[]
Set the fractional part of a Money
.
Arguments
money
is anyMoney.t/0
fraction
is an integer amount that will be set as the fraction of themoney
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.new(:USD, "2.99")
iex> Money.put_fraction Money.new(:USD, "2.49"), 0
Money.new(: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"}}
Round a Money
value into the acceptable range for the requested currency.
Arguments
money
is anyMoney.t/0
opts
is a keyword list of options
Options
:rounding_mode
that defines how the number will be rounded. SeeDecimal.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 as0.05
when its a cash amount. The rounding increment is applied when the option:currency_digits
is set to:cash
Digital Tokens (crypto currencies) do not have formal definitions of decimal digits or rounding strategies. Therefore the
money
is returned unmodified.
Examples
iex> Money.round Money.new("123.73", :CHF), currency_digits: :cash
Money.new(:CHF, "123.75")
iex> Money.round Money.new("123.73", :CHF), currency_digits: 0
Money.new(:CHF, "124")
iex> Money.round Money.new("123.7456", :CHF)
Money.new(:CHF, "123.75")
iex> Money.round Money.new("123.7456", :JPY)
Money.new(:JPY, "124")
@spec 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 anyMoney.t/0
parts
is an integer number of parts into which themoney
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}
Subtract one Money
value struct from another.
Options
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.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)}
Subtract one Money
value struct from another and raise on error.
Returns either {:ok, money}
or {:error, reason}
.
Arguments
money_1
andmoney_2
are any validMoney.t/0
types returned byMoney.new/2
Returns
a
Money.t/0
struct orraises an exception
Examples
iex> Money.sub! Money.new(:USD, 200), Money.new(:USD, 100)
Money.new(: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 \\ latest_rates_or_empty_map())
View Source (since 5.3.0)@spec sum( [t(), ...], Money.ExchangeRates.t() | {:ok, Money.ExchangeRates.t()} | {:error, {module(), String.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 validMoney.t/0
types returned byMoney.new/2
.rates
is a map of exchange rates. The default is the rates returned byMoney.ExchangeRates.latest_rates/0
. If the exchange rates retriever is not running, then the default is%{}
.
Returns
{:ok, money}
representing the sum of the maybe converted money amounts. The currency of the sum is the currency of the firstMoney
in themoney_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())
View Source@spec 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 anyMoney.t/0
struct returned byCldr.Currency.new/2
.to_currency
is a valid currency code into which themoney
is converted.rates
is aMap
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 fromMoney.ExchangeRates.latest_rates/0
.
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 Cldr.LanguageTag.t/0
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())
View Source@spec 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 or raises on error.
Arguments
money
is anyMoney.t/0
struct returned byCldr.Currency.new/2
.to_currency
is a valid currency code into which themoney
is converted.rates
is aMap
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 fromMoney.ExchangeRates.latest_rates/0
.
Examples
iex> Money.to_currency! Money.new(:USD, 100), :AUD,
...> %{USD: Decimal.new(1), AUD: Decimal.from_float(0.7345)}
Money.new(:AUD, "73.4500")
iex> Money.to_currency! Money.new("USD", 100), "AUD",
...> %{"USD" => Decimal.new(1), "AUD" => Decimal.from_float(0.7345)}
Money.new(: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
Returns the currecny code of a Money
type
as an atom
.
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
.
Returns
- the currency code as an
t:atom
.
Example
iex> m = Money.new("USD", 100)
iex> Money.to_currency_code(m)
:USD
Returns the amount part of a Money
type as a Decimal
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
Returns
- a
Decimal.t
Example
iex> m = Money.new("USD", 100)
iex> Money.to_decimal(m)
Decimal.new(100)
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 anyMoney.t/0
struct returned byCldr.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.new(: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.new(:USD, "200.00")
iex> Money.to_integer_exp(m)
{:USD, 20000, -2, Money.new(:USD, "0.00")}
@spec 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.t/0
.
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 validMoney.t/0
type returned byMoney.new/2
options
is a keyword list of options or a%Cldr.Number.Format.Options{}
struct
Returns
{:ok, string}
or{:error, reason}
Options
:backend
is any CLDR backend module. The default isMoney.default_backend()
.currency_symbol
: Allows overriding a currency symbol. The alternatives are::iso
the ISO currency code will be used instead of the default currency symbol.:narrow
uses the narrow symbol defined for the locale. The same narrow symbol can be defined for more than one currency and therefore this should be used with care. If no narrow symbol is defined, the standard symbol is used.:symbol
uses the standard symbol defined in CLDR. A symbol is unique for each currency and can be safely used.- "string" uses
string
as the currency symbol :standard
(the default and recommended) uses the CLDR-defined symbol based upon the currency format for the locale.
:no_fraction_if_integer
is a boolean which, iftrue
, will set:fractional_digits
to0
if the money value is an integer value.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(:USD, 1234), no_fraction_if_integer: true
{:ok, "$1,234"}
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(:THB, 1234, fractional_digits: 4)
{:ok, "THB 1,234.0000"}
iex> Money.to_string Money.new(:USD, 1234), format: :long
{:ok, "1,234 US dollars"}
@spec to_string!(t(), Keyword.t() | Cldr.Number.Format.Options.t()) :: String.t() | no_return()
Returns a formatted string representation of a Money.t/0
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 validMoney.t/0
type returned byMoney.new/2
options
is a keyword list of options or a%Cldr.Number.Format.Options{}
struct
Options
:backend
is any CLDR backend module. The default isMoney.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"
Return a zero amount Money.t/0
in the given currency.
Arguments
money_or_currency
is either aMoney.t/0
or a currency codeoptions
is a keyword list of options passed toMoney.new/3
. The default is[]
.
Example
iex> Money.zero(:USD)
Money.new(:USD, "0")
iex> money = Money.new(:USD, 200)
iex> Money.zero(money)
Money.new(:USD, "0")
iex> Money.zero :ZZZ
{:error, {Cldr.UnknownCurrencyError, "The currency :ZZZ is invalid"}}
Returns a boolean indicating if Money.t/0
has a zero value.
Arguments
money
is any validMoney.t/0
type returned byMoney.new/2
Example
iex> Money.zero?(Money.new(:USD, 0))
true
iex> Money.zero?(Money.new(:USD, 1))
false
iex> Money.zero?(Money.new(:USD, -1))
false