# View Source ExCatalog.Cldr.Money(ex_catalog v1.5.6)

A backend module for Money.

This module provides the same api as the Money module however:

• It matches the standard behaviour of other `ex_cldr` based libraries in maintaining the main public API on the backend module

• It does not require the `:backend` option to be provided since that is implied through the use of the backend module.

All the functions in this module delegate to the functions in `Money`.

# Link to this section Summary

## Functions

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

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.

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.t/0` struct from a currency code and a float amount, or an error tuple of the form `{:error, {exception, message}}`.

Returns a `Money.t/0` 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.

Multiply a `Money` value by a number.

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

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

Returns a `Money.t/0` struct from a currency code and a currency amount. Raises an exception if the current code is invalid.

Normalizes the underlying `Decimal` amount on the given `Money.t/0`.

Parse a string and return a `Money.t/0` or an error.

Set the fractional part of a `Money`.

reduce(money) deprecated

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.

Convert `money` from one currency to another.

Convert `money` from one currency to another and raises on error

Returns the amount part of a `Money` type as a `Decimal`

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

Returns a formatted string representation of a `Money{}`.

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

Return a zero amount `t:Money` in the given currency.

# abs(money)

View Source
`@spec abs(money :: Money.t()) :: Money.t()`

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

## example Example

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

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

Add two `Money` values.

## returns Returns

• `{:ok, money}` or

• `{:error, reason}`

## example Example

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

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

View Source

Add two `Money` values and raise on error.

## returns Returns

• `{:ok, money}` or

• raises an exception

## examples Examples

``````iex> ExCatalog.Cldr.Money.add! Money.new(:USD, 200), Money.new(:USD, 100)
Money.new(:USD, "300")

# cmp(money_1, money_2)

View Source
```@spec cmp(money_1 :: Money.t(), money_2 :: Money.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.

## returns Returns

• `-1` | `0` | `1` or

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

## examples Examples

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

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

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

iex> ExCatalog.Cldr.Money.cmp Money.new(:USD, 200), Money.new(:CAD, 500)
{:error,
{ArgumentError,

# cmp!(money_1, money_2)

View Source

Compares two `Money` values numerically and raises on error.

## returns Returns

• `-1` | `0` | `1` or

• raises an exception

## examples Examples

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

# compare(money_1, money_2)

View Source
```@spec compare(money_1 :: Money.t(), money_2 :: Money.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.

## returns Returns

• `:gt` | `:eq` | `:lt` or

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

## examples Examples

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

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

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

iex> ExCatalog.Cldr.Money.compare Money.new(:USD, 200), Money.new(:CAD, 500)
{:error,
{ArgumentError,

# compare!(money_1, money_2)

View Source

Compares two `Money` values numerically and raises on error.

## returns Returns

• `:gt` | `:eq` | `:lt` or

• raises an exception

## examples Examples

``````ExCatalog.Cldr.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 \\ ExchangeRates.latest_rates())

View Source
```@spec cross_rate(
Money.t() | Money.currency_code(),
Money.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

``````ExCatalog.Cldr.Money.cross_rate(Money.new(:USD, 100), :AUD, %{USD: Decimal.new(1), AUD: Decimal.new("0.7345")})
{:ok, Decimal.new("0.7345")}

ExCatalog.Cldr.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 \\ ExchangeRates.latest_rates())

View Source
```@spec cross_rate!(
Money.t() | Money.currency_code(),
Money.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> ExCatalog.Cldr.Money.cross_rate!(Money.new(:USD, 100), :AUD, %{USD: Decimal.new(1), AUD: Decimal.new("0.7345")})
Decimal.new("0.7345")

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

ExCatalog.Cldr.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_1, number)

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

Divide a `Money` value by a number.

## arguments Arguments

Note that dividing one `Money.t/0` by another is not supported.

## returns Returns

• `{:ok, money}` or

• `{:error, reason}`

## example Example

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

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

# div!(money, number)

View Source

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

## examples Examples

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

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

# equal?(money_1, money_2)

View Source
`@spec equal?(money_1 :: Money.t(), money_2 :: Money.t()) :: boolean()`

Returns a boolean indicating if two `Money` values are equal

## returns Returns

• `true` or `false`

## example Example

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

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

# from_float(currency_code, amount, options \\ [])

View Source (since 2.0.0)
```@spec from_float(
float() | Money.currency_code(),
float() | Money.currency_code(),
Keyword.t()
) ::
Money.t() | {:error, {module(), String.t()}}```

Returns a `Money.t/0` 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

## examples Examples

``````iex> ExCatalog.Cldr.Money.from_float 1.23456, :USD
Money.new(:USD, "1.23456")

iex> ExCatalog.Cldr.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, options \\ [])

View Source
```@spec from_float!(Money.currency_code(), float(), Keyword.t()) ::
Money.t() | no_return()```

Returns a `Money.t/0` 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 three-character upcased binary or atom

• `amount` is a float

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

## examples Examples

``````iex> ExCatalog.Cldr.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``````

# from_integer(amount, currency, options \\ [])

View Source
```@spec from_integer(integer(), Money.currency_code(), Keyword.t()) ::
Money.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 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.

## examples Examples

``````iex> ExCatalog.Cldr.Money.from_integer(20000, :USD)
Money.new(:USD, "200.00")

iex> ExCatalog.Cldr.Money.from_integer(200, :JPY)
Money.new(:JPY, "200")

iex> ExCatalog.Cldr.Money.from_integer(20012, :USD)
Money.new(:USD, "200.12")

iex> ExCatalog.Cldr.Money.from_integer(20012, :COP)
Money.new(:COP, "200.12")``````

View Source

View Source

View Source

View Source

# mult(money, number)

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

Multiply a `Money` value by a number.

## arguments Arguments

Note that multipling one `Money.t/0` by another is not supported.

## returns Returns

• `{:ok, money}` or

• `{:error, reason}`

## example Example

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

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

# mult!(money, number)

View Source
`@spec mult!(Money.t(), Cldr.Math.number_or_decimal()) :: Money.t() | none()`

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

## returns Returns

• raises an exception

## examples Examples

``````iex> ExCatalog.Cldr.Money.mult!(Money.new(:USD, 200), 2)
Money.new(:USD, "400")

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

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

View Source
```@spec new(
Money.amount() | Money.currency_code(),
Money.amount() | Money.currency_code(),
Keyword.t()
) ::
Money.t() | {:error, {module(), String.t()}}```

Returns a `Money.t/0` 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

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

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

## examples Examples

``````iex> ExCatalog.Cldr.Money.new(:USD, 100)
Money.new(:USD, "100")

iex> ExCatalog.Cldr.Money.new(100, :USD)
Money.new(:USD, "100")

iex> ExCatalog.Cldr.Money.new("USD", 100)
Money.new(:USD, "100")

iex> ExCatalog.Cldr.Money.new("thb", 500)
Money.new(:THB, "500")

iex> ExCatalog.Cldr.Money.new("EUR", Decimal.new(100))
Money.new(:EUR, "100")

iex> ExCatalog.Cldr.Money.new(:EUR, "100.30")
Money.new(:EUR, "100.30")

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

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

iex> ExCatalog.Cldr.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 \\ [])

View Source
```@spec new!(
Money.amount() | Money.currency_code(),
Money.amount() | Money.currency_code(),
Keyword.t()
) ::
Money.t() | no_return()```

Returns a `Money.t/0` 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 three-character upcased binary or atom

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

# normalize(money)

View Source (since 5.0.0)
`@spec normalize(Money.t()) :: Money.t()`

Normalizes the underlying `Decimal` amount on the 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 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(string, options \\ [])

View Source (since 3.2.0)
`@spec parse(String.t(), Keyword.t()) :: Money.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_name` is any valid locale name returned by `Cldr.known_locale_names/1` or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2` The default is `<backend>.get_locale()`

• `currency_filter` is an `atom` or list of `atoms` representing the currency types to be considered for a match. If a list of atoms is given, the currency must meet all criteria for it to be considered.

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

• `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.

## examples Examples

``````iex> ExCatalog.Cldr.Money.parse("USD 100")
Money.new(:USD, "100")

iex> ExCatalog.Cldr.Money.parse "USD 100,00", locale: "de"
Money.new(:USD, "100.00")

iex> ExCatalog.Cldr.Money.parse("100 USD")
Money.new(:USD, "100")

iex> ExCatalog.Cldr.Money.parse("100 eurosports", fuzzy: 0.8)
Money.new(:EUR, "100")

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

iex> ExCatalog.Cldr.Money.parse("100 afghan afghanis")
Money.new(:AFN, "100")

iex> ExCatalog.Cldr.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> ExCatalog.Cldr.Money.parse("USD 100 with trailing text")
{:error,
{Money.ParseError, "Could not parse \"USD 100 with trailing text\"."}}``````

# put_fraction(money, upto)

View Source

Set the fractional part of a `Money`.

## arguments Arguments

• `money` is a `Money.t/0` struct

• `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> ExCatalog.Cldr.Money.put_fraction Money.new(:USD, "2.49"), 99
Money.new(:USD, "2.99")

iex> ExCatalog.Cldr.Money.put_fraction Money.new(:USD, "2.49"), 0
Money.new(:USD, "2.0")

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

# reduce(money)

View Source
This function is deprecated. Use ExCatalog.Cldr.Money.normalize/1 instead..

# round(money, options \\ [])

View Source
`@spec round(Money.t(), Keyword.t()) :: Money.t()`

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

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

## examples Examples

``````iex> ExCatalog.Cldr.Money.round Money.new("123.73", :CHF), currency_digits: :cash
Money.new(:CHF, "123.75")

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

iex> ExCatalog.Cldr.Money.round Money.new("123.7456", :CHF)
Money.new(:CHF, "123.75")

iex> ExCatalog.Cldr.Money.round Money.new("123.7456", :JPY)
Money.new(:JPY, "124")``````

# split(money, parts)

View Source
`@spec split(Money.t(), non_neg_integer()) :: {Money.t(), Money.t()}`

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

## arguments Arguments

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

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

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

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

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

# sub(money_1, money_2)

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

Subtract one `Money` value struct from another.

## returns Returns

• `{:ok, money}` or

• `{:error, reason}`

## example Example

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

# sub!(money_1, money_2)

View Source
`@spec sub!(money_1 :: Money.t(), money_2 :: Money.t()) :: Money.t() | none()`

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

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

## examples Examples

``````iex> ExCatalog.Cldr.Money.sub! Money.new(:USD, 200), Money.new(:USD, 100)
Money.new(:USD, "100")

** (ArgumentError) Cannot subtract monies with different currencies. Received :USD and :CAD.``````

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

View Source
```@spec to_currency(
Money.t(),
Money.currency_code(),
Money.ExchangeRates.t()
| {:ok, Money.ExchangeRates.t()}
| {:error, {module(), String.t()}}
) :: {:ok, Money.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()`

## examples Examples

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

ExCatalog.Cldr.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> ExCatalog.Cldr.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> ExCatalog.Cldr.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, currency, rates \\ ExchangeRates.latest_rates())

View Source
```@spec to_currency!(
Money.t(),
Money.currency_code(),
Money.ExchangeRates.t()
| {:ok, Money.ExchangeRates.t()}
| {:error, {module(), String.t()}}
) :: Money.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> ExCatalog.Cldr.Money.to_currency! Money.new(:USD, 100), :AUD, %{USD: Decimal.new(1), AUD: Decimal.from_float(0.7345)}
Money.new(:AUD, "73.4500")

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

ExCatalog.Cldr.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)

View Source
`@spec to_decimal(money :: Money.t()) :: Decimal.t()`

Returns the amount part of a `Money` type as a `Decimal`

## returns Returns

• a `Decimal.t`

## example Example

``````iex> m = ExCatalog.Cldr.Money.new("USD", 100)
iex> ExCatalog.Cldr.Money.to_decimal(m)
Decimal.new("100")``````

# to_integer_exp(money)

View Source

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.

## 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 = ExCatalog.Cldr.Money.new(:USD, "200.012356")
Money.new(:USD, "200.012356")
iex> ExCatalog.Cldr.Money.to_integer_exp(m)
{:USD, 20001, -2, Money.new(:USD, "0.002356")}

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

# to_string(money, options \\ [])

View Source
```@spec to_string(Money.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.

## returns Returns

• `{:ok, string}` or

• `{:error, reason}`

## examples Examples

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

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

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

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

# to_string!(money, options \\ [])

View Source
`@spec to_string!(Money.t(), Keyword.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.

## examples Examples

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

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

iex> ExCatalog.Cldr.Money.to_string! Money.new(:THB, 1234)
"THB 1,234.00"

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

View Source

# zero(money, options \\ [])

View Source
`@spec zero(Money.currency_code() | Money.t(), Keyword.t()) :: Money.t()`

Return a zero amount `t:Money` in the given currency.

## arguments Arguments

• `money_or_currency` is either a `t:Money` or a currency code

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

## example Example

``````iex> ExCatalog.Cldr.Money.zero(:USD)
Money.new(:USD, "0")

iex> money = Money.new(:USD, 200)
iex> ExCatalog.Cldr.Money.zero(money)
Money.new(:USD, "0")

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