@spec abs(money :: t()) :: t()

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

arguments

Arguments

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

returns

Returns

• a Money.t/0

example

Example

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

@spec add!(money_1 :: t(), money_2 :: t()) :: t() | no_return()

Add two Money values and raise on error.

arguments

Arguments

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

returns

Returns

• a Money.t/0 struct or

• raises an exception

examples

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.

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

Add two Money values.

arguments

Arguments

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

returns

Returns

• {:ok, money} or

• {:error, reason}

example

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."}}

Compares two Money values numerically and raises on error.

arguments

Arguments

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

returns

Returns

• -1 | 0 | 1 or

• raises an exception

examples

Examples

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

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

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

Arguments

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

returns

Returns

• -1 | 0 | 1 or

• {:error, {module(), String.t}}

examples

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

Arguments

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

returns

Returns

• :gt | :eq | :lt or

• raises an exception

examples

Examples

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

@spec 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

Arguments

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

returns

Returns

• :gt | :eq | :lt or

• {:error, {module(), String.t}}

examples

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."}}

@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

Arguments

• from is any Money.t/0 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

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

@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

Arguments

• from is any Money.t/0 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

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

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()) :: t() | none()

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

arguments

Arguments

• money is any valid Money.t/0 types returned by Money.new/2

• number is an integer, float or Decimal.t

returns

Returns

• a Money.t/0 struct or

• raises an exception

examples

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"

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

Divide a Money value by a number.

arguments

Arguments

• money is any valid Money.t/0 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

Returns

• {:ok, money} or

• {:error, reason}

example

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 equal?(money_1 :: t(), money_2 :: t()) :: boolean()

Returns a boolean indicating if two Money values are equal

arguments

Arguments

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

returns

Returns

• true or false

example

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!(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

Arguments

• currency_code is an ISO4217 binary or atom currency code or an ISO 24165 token identifier or shortname.

• amount is a float

• options is a keyword list of options passed to Money.new/3. The default is [].

examples

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_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

Arguments

• currency_code is an ISO4217 binary or atom currency code or an ISO 24165 token identifier or shortname.

• amount is a float

• options is a keyword list of options passed to Money.new/3. The default is [].

examples

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_integer(integer(), currency_code(), Keyword.t()) ::
  t() | {:error, {module(), String.t()}}

Convert an integer representation of money into a Money struct.

arguments

Arguments

• integer is an integer representation of a money amount including any decimal digits. ie. 20000 would be interpreted to mean $200.00 if the currency is :USD and no :fractional_digits option was provided.

• currency is the currency code for the integer. The assumed decimal precision is derived from the currency code if no fractional_digits option is specified.

• options is a keyword list of options.

options

Options

• :fractional_digits which determines the currency precision implied by the integer. 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

Returns

• A Money.t/0 struct or

• {:error, {exception, message}}

notes

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

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")

See Cldr.known_currencies/0.

See Money.Currency.known_current_currencies/0.

See Money.Currency.known_historic_currencies/0.

See Money.Currency.known_tender_currencies/0.

@spec localize(t(), Keyword.t()) :: {:ok, t()} | {:error, {module(), String.t()}}

Localizes a Money by converting it to the currency of the specified locale.

arguments

Arguments

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

• options is a keyword list of options.

options

Options

• :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()

• :backend is any module() that includes use Cldr and therefore is a Cldr backend module(). The default is Money.default_backend()

returns

Returns

• {:ok, localized_money} or

• {:error, {exception, reason}}

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

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

arguments

Arguments

• money is any valid Money.t/0 types returned by Money.new/2

• number is an integer, float or Decimal.t

returns

Returns

• a Money.t/0 or

• raises an exception

examples

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

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

Multiply a Money value by a number.

arguments

Arguments

• money is any valid Money.t/0 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

Returns

• {:ok, money} or

• {:error, reason}

example

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 negative?(t()) :: boolean()

Returns a boolean indicating if Money.t/0 has a negative value.

arguments

Arguments

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

example

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() | no_return()

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

arguments

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

Examples

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

@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

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

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 ".". The default is Cldr.get_locale/0.

• :backend is any module() that includes use Cldr and therefore is a Cldr backend module(). The default is Money.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

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 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

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

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

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

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

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

Returns

• a Money.t/0 if parsing is successful or

• {:error, {exception, reason}} if an error is detected.

notes

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

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\"."}}

@spec positive?(t()) :: boolean()

Returns a boolean indicating if Money.t/0 has a positive value.

arguments

Arguments

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

example

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

@spec put_format_options(t(), Keyword.t()) :: t()

Add format options to a Money.t/0.

arguments

Arguments

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

• options is a keyword list of options. These options are used when calling Money.to_string/2. The default is []

Set the fractional part of a Money.

arguments

Arguments

• money is any Money.t/0

• fraction is an integer amount that will be set as the fraction of the money

notes

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

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"}}

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

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

arguments

Arguments

• money is any Money.t/0

• opts is a keyword list of options

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

Notes

There are two kinds of rounding applied:

1. Round to the appropriate number of fractional digits

2. 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

3. Digital Tokens (crypto currencies) do not have formal definitions of decimal digits or rounding strategies. Therefore the money is returned unmodified.

examples

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

Arguments

• money is any Money.t/0

• 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:

1. Round the money amount to the required currency precision using Money.round/1

2. Divide the result of step 1 by the integer divisor

3. Round the result of the division to the precision of the currency using Money.round/1

4. Return two numbers: the result of the division and any remainder that could not be applied given the precision of the currency.

examples

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}

@spec 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

Arguments

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

returns

Returns

• a Money.t/0 struct or

• raises an exception

examples

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.

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

Subtract one Money value struct from another.

options

Options

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

returns

Returns

• {:ok, money} or

• {:error, reason}

example

Example

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

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

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

arguments

Arguments

• money_list is a list of any valid Money.t/0 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

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

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)}

@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 and raises on error

arguments

Arguments

• money is any Money.t/0 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

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

@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

Arguments

• money is any Money.t/0 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

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

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"}}

@spec to_currency_code(money :: t()) :: atom()

Returns the currecny code of a Money type as an atom.

arguments

Arguments

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

returns

Returns

• the currency code as an t:atom

example

Example

iex> m = Money.new("USD", 100)
iex> Money.to_currency_code(m)
:USD

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

Returns the amount part of a Money type as a Decimal

arguments

Arguments

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

returns

Returns

• a Decimal.t

example

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

Options

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

notes

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

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

Arguments

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

• options is a keyword list of options or a %Cldr.Number.Format.Options{} struct

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

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"

@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{}.

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

Arguments

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

• options is a keyword list of options or a %Cldr.Number.Format.Options{} struct

returns

Returns

• {:ok, string} or

• {:error, reason}

options

Options

• :backend is any CLDR backend module. The default is Money.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.

• Any other options are passed to Cldr.Number.to_string/3

examples

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(: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"}

Return a zero amount Money.t/0 in the given currency.

arguments

Arguments

• money_or_currency is either a Money.t/0 or a currency code

• options is a keyword list of options passed to Money.new/3. The default is [].

example

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"}}

@spec zero?(t()) :: boolean()

Returns a boolean indicating if Money.t/0 has a zero value.

arguments

Arguments

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

example

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