View Source Money (Money v1.13.1)

Defines a Money struct along with convenience methods for working with currencies.

Examples

iex> money = Money.new(500, :USD)
%Money{amount: 500, currency: :USD}
iex> money = Money.add(money, 550)
%Money{amount: 1050, currency: :USD}
iex> Money.to_string(money)
"$10.50"

Configuration

You can set defaults in your Mix configuration to make working with Money a little easier.

config :money,
  default_currency: :EUR,                    # this allows you to do Money.new(100)
  separator: ".",                            # change the default thousands separator for Money.to_string
  delimiter: ",",                            # change the default decimal delimiter for Money.to_string
  symbol: false,                             # don’t display the currency symbol in Money.to_string
  symbol_on_right: false,                    # position the symbol
  symbol_space: false,                       # add a space between symbol and number
  fractional_unit: true,                     # display units after the delimiter
  strip_insignificant_zeros: false,          # don’t display the insignificant zeros or the delimiter
  code: false,                               # add the currency code after the number
  minus_sign_first: true,                    # display the minus sign before the currency symbol for Money.to_string
  strip_insignificant_fractional_unit: false # don't display the delimiter or fractional units if the fractional units are only insignificant zeros

Summary

Functions

abs(money)

Returns a Money with the arithmetical absolute of the amount.

add(m, addend)

Adds two Money together or an integer (cents) amount to a Money

cmp(a, b)

Compares two Money structs with each other. They must each be of the same currency and then their amounts are compared. If the first amount is larger than the second :gt is returned, if less than :lt is returned, if both amounts are equal :eq is returned.

compare(a, b)

Compares two Money structs with each other. They must each be of the same currency and then their amounts are compared. If the first amount is larger than the second 1 is returned, if less than -1 is returned, if both amounts are equal 0 is returned.

divide(money, denominator)

Divides up Money by an amount

equals?(money1, money2)

Returns true if two Money of the same currency have the same amount

multiply(money, multiplier)

Multiplies a Money by an amount

neg(money)

Returns a Money with the amount negated.

negative?(money)

Returns true if the amount of a Money is less than zero

new(amount)

Create a new Money struct using a default currency. The default currency can be set in the system Mix config.

new(int, currency)

Create a new Money struct from currency sub-units (cents)

parse(value, currency \\ nil, opts \\ [])

Parse a value into a Money type.

parse!(value, currency \\ nil, opts \\ [])

Parse a value into a Money type. Similar to parse/3 but returns a %Money{} or raises an error if parsing fails.

positive?(money)

Returns true if the amount of a Money is greater than zero

round(money, places \\ 0)

Rounds a Money struct using a given number of places. round respects the rounding mode within the current Decimal context.

subtract(m, subtractend)

Subtracts one Money from another or an integer (cents) from a Money

to_decimal(money)

Converts a Money struct to a Decimal representation

to_string(money, opts \\ [])

Converts a Money struct to a string representation

zero?(money)

Returns true if the amount of a Money struct is zero

Types

t()

@type t() :: %Money{amount: integer(), currency: atom()}

Functions

abs(money)

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

Returns a Money with the arithmetical absolute of the amount.

Examples

iex> Money.new(-100, :USD) |> Money.abs
%Money{amount: 100, currency: :USD}

iex> Money.new(100, :USD) |> Money.abs
%Money{amount: 100, currency: :USD}

add(m, addend)

@spec add(t(), t() | integer() | float()) :: t()

Adds two Money together or an integer (cents) amount to a Money

Examples

iex> Money.add(Money.new(100, :USD), Money.new(50, :USD))
%Money{amount: 150, currency: :USD}

iex> Money.add(Money.new(100, :USD), 50)
%Money{amount: 150, currency: :USD}

iex> Money.add(Money.new(100, :USD), 5.55)
%Money{amount: 655, currency: :USD}

cmp(a, b)

@spec cmp(t(), t()) :: :lt | :eq | :gt

See compare/2 for a similar function that returns -1, 0 or 1 instead.

Examples

iex> Money.cmp(Money.new(100, :USD), Money.new(100, :USD))
:eq

iex> Money.cmp(Money.new(100, :USD), Money.new(101, :USD))
:lt

iex> Money.cmp(Money.new(101, :USD), Money.new(100, :USD))
:gt

compare(a, b)

@spec compare(t(), t()) :: -1 | 0 | 1

See cmp/2 for a similar function that returns :lt, :eq or :gt instead.

Examples

iex> Money.compare(Money.new(100, :USD), Money.new(100, :USD))
0

iex> Money.compare(Money.new(100, :USD), Money.new(101, :USD))
-1

iex> Money.compare(Money.new(101, :USD), Money.new(100, :USD))
1

divide(money, denominator)

@spec divide(t(), integer()) :: [t()]

Divides up Money by an amount

Examples

iex> Money.divide(Money.new(100, :USD), 2)
[%Money{amount: 50, currency: :USD}, %Money{amount: 50, currency: :USD}]

iex> Money.divide(Money.new(101, :USD), 2)
[%Money{amount: 51, currency: :USD}, %Money{amount: 50, currency: :USD}]

equals?(money1, money2)

@spec equals?(t(), t()) :: boolean()

Returns true if two Money of the same currency have the same amount

Examples

iex> Money.equals?(Money.new(100, :USD), Money.new(100, :USD))
true

iex> Money.equals?(Money.new(101, :USD), Money.new(100, :USD))
false

iex> Money.equals?(Money.new(100, :USD), Money.new(100, :CAD))
false

multiply(money, multiplier)

@spec multiply(t(), integer() | float() | Decimal.t()) :: t()

Multiplies a Money by an amount

Examples

iex> Money.multiply(Money.new(100, :USD), 10)
%Money{amount: 1000, currency: :USD}

iex> Money.multiply(Money.new(100, :USD), 1.5)
%Money{amount: 150, currency: :USD}

neg(money)

@spec neg(t()) :: t()

Returns a Money with the amount negated.

Examples

iex> Money.new(100, :USD) |> Money.neg
%Money{amount: -100, currency: :USD}

iex> Money.new(-100, :USD) |> Money.neg
%Money{amount: 100, currency: :USD}

negative?(money)

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

Returns true if the amount of a Money is less than zero

Examples

iex> Money.negative?(Money.new(0, :USD))
false

iex> Money.negative?(Money.new(1, :USD))
false

iex> Money.negative?(Money.new(-1, :USD))
true

new(amount)

@spec new(integer()) :: t()

Create a new Money struct using a default currency. The default currency can be set in the system Mix config.

Config

config :money,
  default_currency: :USD

Examples

Money.new(123)
%Money{amount: 123, currency: :USD}

new(int, currency)

@spec new(integer(), atom() | String.t()) :: t()

Create a new Money struct from currency sub-units (cents)

Examples

iex> Money.new(1_000_00, :USD)
%Money{amount: 1_000_00, currency: :USD}

parse(value, currency \\ nil, opts \\ [])

@spec parse(String.t() | number() | Decimal.t(), atom() | String.t(), Keyword.t()) ::
  {:ok, t()} | :error

Parse a value into a Money type.

The following options are available:

:separator - default ",", sets the separator for groups of thousands. "1,000"
:delimiter - default ".", sets the decimal delimiter. "1.23"

Examples

iex> Money.parse("$1,234.56", :USD)
{:ok, %Money{amount: 123456, currency: :USD}}

iex> Money.parse("1.234,56", :EUR, separator: ".", delimiter: ",")
{:ok, %Money{amount: 123456, currency: :EUR}}

iex> Money.parse("1.234,56", :WRONG)
:error

iex> Money.parse(1_234.56, :USD)
{:ok, %Money{amount: 123456, currency: :USD}}

iex> Money.parse(1_234, :USD)
{:ok, %Money{amount: 123400, currency: :USD}}

iex> Money.parse(-1_234.56, :USD)
{:ok, %Money{amount: -123456, currency: :USD}}

iex> Money.parse(Decimal.from_float(1_234.56), :USD)
{:ok, %Money{amount: 123456, currency: :USD}}

parse!(value, currency \\ nil, opts \\ [])

@spec parse!(String.t() | number() | Decimal.t(), atom() | String.t(), Keyword.t()) ::
  t()

Parse a value into a Money type. Similar to parse/3 but returns a %Money{} or raises an error if parsing fails.

Examples

iex> Money.parse!("1,234.56", :USD)
%Money{amount: 123456, currency: :USD}

iex> Money.parse!("wrong", :USD)
** (ArgumentError) unable to parse "wrong" with currency :USD

positive?(money)

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

Returns true if the amount of a Money is greater than zero

Examples

iex> Money.positive?(Money.new(0, :USD))
false

iex> Money.positive?(Money.new(1, :USD))
true

iex> Money.positive?(Money.new(-1, :USD))
false

round(money, places \\ 0)

@spec round(t(), integer()) :: t()

Rounds a Money struct using a given number of places. round respects the rounding mode within the current Decimal context.

By default round rounds to zero decimal places, using the currency's exponent. This results in rounding to whole values of the currency. Currencies without an exponent are not rounded unless a different value is passed for places other than the default.

Examples

iex> Money.round(Money.new(123456, :GBP))
%Money{amount: 123500, currency: :GBP}

iex> Money.round(Money.new(-123420, :EUR))
%Money{amount: -123400, currency: :EUR}

iex> Money.round(Money.new(-123420, :EUR), -3)
%Money{amount: -100000, currency: :EUR}

# Round to tenth of exponent
iex> Money.round(Money.new(123425, :EUR), 1)
%Money{amount: 123430, currency: :EUR}

# Currencies round based on their exponent
iex> Money.round(Money.new(820412, :JPY))
%Money{amount: 820412, currency: :JPY}

iex> Money.round(Money.new(820412, :JPY), -3)
%Money{amount: 820000, currency: :JPY}

subtract(m, subtractend)

@spec subtract(t(), t() | integer() | float()) :: t()

Subtracts one Money from another or an integer (cents) from a Money

Examples

iex> Money.subtract(Money.new(150, :USD), Money.new(50, :USD))
%Money{amount: 100, currency: :USD}

iex> Money.subtract(Money.new(150, :USD), 50)
%Money{amount: 100, currency: :USD}

iex> Money.subtract(Money.new(150, :USD), 1.25)
%Money{amount: 25, currency: :USD}

to_decimal(money)

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

Converts a Money struct to a Decimal representation

Examples

iex> Money.to_decimal(Money.new(123456, :GBP))
Decimal.new("1234.56")

iex> Money.to_decimal(Money.new(-123420, :EUR))
Decimal.new("-1234.20")

to_string(money, opts \\ [])

@spec to_string(t(), Keyword.t()) :: String.t()

Converts a Money struct to a string representation

The following options are available:

:separator - default ",", sets the separator for groups of thousands. "1,000"
:delimiter - default ".", sets the decimal delimiter. "1.23"
:symbol - default true, sets whether to display the currency symbol or not.
:symbol_on_right - default false, display the currency symbol on the right of the number, eg: 123.45€
:symbol_space - default false, add a space between currency symbol and number, eg: € 123,45 or 123.45 €
:fractional_unit - default true, show the remaining units after the delimiter
:strip_insignificant_zeros - default false, strip zeros after the delimiter
:code - default false, append the currency code after the number
:minus_sign_first - default true, display the minus sign before the currency symbol for negative values
:strip_insignificant_fractional_unit - default false, don't display the delimiter or fractional units if the fractional units are only insignificant zeros

Examples

iex> Money.to_string(Money.new(123456, :GBP))
"£1,234.56"

iex> Money.to_string(Money.new(123456, :EUR), separator: ".", delimiter: ",")
"€1.234,56"

iex> Money.to_string(Money.new(123456, :EUR), symbol: false)
"1,234.56"

iex> Money.to_string(Money.new(123456, :EUR), symbol: false, separator: "")
"1234.56"

iex> Money.to_string(Money.new(123456, :EUR), fractional_unit: false)
"€1,234"

iex> Money.to_string(Money.new(123450, :EUR), strip_insignificant_zeros: true)
"€1,234.5"

iex> Money.to_string(Money.new(123450, :EUR), code: true)
"€1,234.50 EUR"

iex> Money.to_string(Money.new(-123450, :EUR))
"-€1,234.50"

iex> Money.to_string(Money.new(-123450, :EUR), minus_sign_first: false)
"€-1,234.50"

iex> Money.to_string(Money.new(123400, :EUR), strip_insignificant_fractional_unit: true)
"€1,234"

iex> Money.to_string(Money.new(123450, :EUR), strip_insignificant_fractional_unit: true)
"€1,234.50"

It can also be interpolated (It implements the String.Chars protocol) To control the formatting, you can use the above options in your config, more information is in the introduction to Money

Examples

iex> "Total: #{Money.new(100_00, :USD)}"
"Total: $100.00"

zero?(money)

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

Returns true if the amount of a Money struct is zero

Examples

iex> Money.zero?(Money.new(0, :USD))
true

iex> Money.zero?(Money.new(1, :USD))
false