Specs

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

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

Arguments

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

• amount is an integer, string or Decimal

• options is a keyword list of options

Options

• :locale is any known locale. The locale is used to normalize any binary (String) amounts to a form that can be consumed 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

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

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

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

iex> Money.new("thb", 500)
#Money<:THB, 500>

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

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

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

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

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

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