Money v1.6.0 Money View Source

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

Example:

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 options

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

Configuration:

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 delimeter 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 delimeter
  strip_insignificant_zeros: false  # don’t display the insignificant zeros or the delimeter

Link to this section Summary

Functions

Returns a Money with the arithmetical absolute of the amount.

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

Compares two Money structs with each other. They must each be of the same currency and then their amounts are compared

Divides up Money by an amount

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

Multiplies a Money by an amount

Returns a Money with the amount negated.

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

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

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

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

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

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

Converts a Money struct to a string representation

Returns true if the amount of a Money struct is zero

Link to this section Types

Link to this type

t()

View Source
t() :: %Money{amount: integer(), currency: atom()}

Link to this section Functions

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}
Link to this function

add(m, addend)

View Source
add(t(), t() | integer() | float()) :: t()

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

Example:

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}
Link to this function

compare(a, b)

View Source
compare(t(), t()) :: -1 | 0 | 1

Compares two Money structs with each other. They must each be of the same currency and then their amounts are compared

Example:

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
Link to this function

divide(money, denominator)

View Source
divide(t(), integer()) :: [t()]

Divides up Money by an amount

Example:

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}]
Link to this function

equals?(a, b)

View Source
equals?(t(), t()) :: boolean()

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

Example:

iex> Money.equals?(Money.new(100, :USD), Money.new(100, :USD))
true
iex> Money.equals?(Money.new(101, :USD), Money.new(100, :USD))
false
Link to this function

multiply(money, multiplier)

View Source
multiply(t(), integer() | float()) :: t()

Multiplies a Money by an amount

Example:

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}

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}
Link to this function

negative?(money)

View Source
negative?(t()) :: boolean()

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

Example:

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

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

Example Config:

config :money,
  default_currency: :USD

Example:

Money.new(123)
%Money{amount: 123, currency: :USD}
Link to this function

new(int, currency)

View Source
new(integer(), atom() | String.t()) :: t()

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

Example:

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

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

View Source
parse(String.t() | float(), 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.56, :USD)
{:ok, %Money{amount: -123456, currency: :USD}}
Link to this function

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

View Source
parse!(String.t() | float(), 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.

Example:

iex> Money.parse!("1,234.56", :USD)
%Money{amount: 123456, currency: :USD}
iex> Money.parse!("wrong", :USD)
** (ArgumentError) unable to parse "wrong"
Link to this function

positive?(money)

View Source
positive?(t()) :: boolean()

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

Example:

iex> Money.positive?(Money.new(0, :USD))
false
iex> Money.positive?(Money.new(1, :USD))
true
iex> Money.positive?(Money.new(-1, :USD))
false
Link to this function

subtract(m, subtractend)

View Source
subtract(t(), t() | integer() | float()) :: t()

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

Example:

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}
Link to this function

to_string(money, opts \\ [])

View Source
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 delimeter
  • strip_insignificant_zeros - default false, strip zeros after the delimeter

Example:

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"

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

Example:

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

Returns true if the amount of a Money struct is zero

Example:

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