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

Arguments

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

Returns

• a Money.t/0

Example

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

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

Add two Money values.

Arguments

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

Returns

• {:ok, money} or

• {:error, reason}

Example

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

iex> SoftBank.Cldr.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 and money_2 are any valid Money.t/0 types returned by Money.new/2

Returns

• {:ok, money} or

• raises an exception

Examples

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

SoftBank.Cldr.Money.add! Money.new(:USD, 200), Money.new(:CAD, 500)
** (ArgumentError) Cannot add two `t:Money.t/0` with different currencies. Received :USD and :CAD.

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

Arguments

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

Returns

• -1 | 0 | 1 or

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

Examples

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

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

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

iex> SoftBank.Cldr.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 and money_2 are any valid Money.t/0 types returned by Money.new/2

Returns

• -1 | 0 | 1 or

• raises an exception

Examples

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

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

Arguments

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

Returns

• :gt | :eq | :lt or

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

Examples

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

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

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

iex> SoftBank.Cldr.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 and money_2 are any valid Money.t/0 types returned by Money.new/2

Returns

• :gt | :eq | :lt or

• raises an exception

Examples

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

@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

• 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

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

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

@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

• 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

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

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

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

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

Divide a Money value by a number.

Arguments

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

• number is an integer, float or Decimal.t/0

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

Returns

• {:ok, money} or

• {:error, reason}

Example

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

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

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

Arguments

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

• number is an integer, float or Decimal.t

Returns

• a Money.t/0 struct or

• raises an exception

Examples

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

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

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

Returns a boolean indicating if two Money values are equal

Arguments

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

Returns

• true or false

Example

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

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

@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

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

• amount is a float

Examples

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

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

@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

• 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

iex> SoftBank.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

@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

• integer is an integer representation of a mooney item including any decimal digits. ie. 20000 would interpreted to mean $200.00

• currency is the currency code for the integer. The assumed decimal places is derived from the currency code.

Returns

• A Money struct or

• {:error, {Cldr.UnknownCurrencyError, message}}

Examples

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

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

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

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

See Cldr.known_currencies/0.

See Money.known_current_currencies/0.

See Money.known_historic_currencies/0.

See Money.known_tender_currencies/0.

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

Multiply a Money value by a number.

Arguments

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

• number is an integer, float or Decimal.t/0

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

Returns

• {:ok, money} or

• {:error, reason}

Example

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

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

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

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

Arguments

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

• number is an integer, float or Decimal.t

Returns

• a Money.t/0 or

• raises an exception

Examples

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

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

@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

• 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

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

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

Examples

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

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

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

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

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

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

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

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

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

@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

• currency_code is an ISO4217 three-character upcased binary or atom

• amount is an integer, float or Decimal

Examples

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

@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

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

• string is a string to be parsed

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

Options

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

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

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

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

Examples

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

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

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

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

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

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

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

Set the fractional part of a Money.

Arguments

• money is a Money.t/0 struct

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

Notes

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

Examples

iex> SoftBank.Cldr.Money.put_fraction Money.new(:USD, "2.49"), 99
Money.new(:USD, "2.99")

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

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

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

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

Arguments

• money is a Money.t/0 struct

• opts is a keyword list of options

Options

• :rounding_mode that defines how the number will be rounded. See Decimal.Context. The default is :half_even which is also known as "banker's rounding"

• :currency_digits which determines the rounding increment. The valid options are :cash, :accounting and :iso or an integer value representing the rounding factor. The default is :iso.

Notes

There are two kinds of rounding applied:

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

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

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

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

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

@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

• 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

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

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

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

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

Subtract one Money value struct from another.

Options

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

Returns

• {:ok, money} or

• {:error, reason}

Example

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

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

Arguments

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

Returns

• a Money.t/0 struct or

• raises an exception

Examples

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

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

@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

• 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

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

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

@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

• 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

iex> SoftBank.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> SoftBank.Cldr.Money.to_currency! Money.new("USD", 100), "AUD", %{"USD" => Decimal.new(1), "AUD" => Decimal.from_float(0.7345)}
Money.new(:AUD, "73.4500")

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

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

Returns the amount part of a Money type as a Decimal

Arguments

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

Returns

• a Decimal.t

Example

iex> m = SoftBank.Cldr.Money.new("USD", 100)
iex> SoftBank.Cldr.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.

Arguments

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

Notes

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

Example

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

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

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

Arguments

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

• options is a keyword list of options

Returns

• {:ok, string} or

• {:error, reason}

Options

• :backend is any CLDR backend module. The default is Money.default_backend().

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

Examples

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

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

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

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

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

Arguments

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

• options is a keyword list of options

Options

• :backend is any CLDR backend module. The default is Money.default_backend().

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

Examples

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

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

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

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

See Cldr.validate_currency/1.

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

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

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

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

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

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