Money v1.0.0 Money

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

Summary

Functions

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

Types

t :: %Money{amount: integer, currency: atom}

Functions

add(m, addend)

Specs

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}
compare(a, b)

Specs

compare(t, t) :: t

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
divide(money, denominator)

Specs

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}]
equals?(a, b)

Specs

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
multiply(money, multiplier)

Specs

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}
negative?(money)

Specs

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
new(amount)

Specs

new(integer) :: t

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}
new(int, currency)

Specs

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}
parse(value, currency \\ nil, opts \\ [])

Specs

parse(String.t | float, atom | String.t, Keyword.t) :: {:ok, t}
parse(String.t | float, atom | String.t, Keyword.t) :: t

Parse a value into a Money type.

The following options are available:

  • separator - default ",", sets the separator for groups of thousands. “1,000”
  • delimeter - default ".", sets the decimal delimeter. “1.23”

Examples:

iex> Money.parse("$1,234.56", :USD)
{:ok, %Money{amount: 123456, currency: :USD}}
iex> Money.parse("1.234,56", :EUR, separator: ".", delimeter: ",")
{: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}}
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.

Example:

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

Specs

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
subtract(m, subtractend)

Specs

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}
to_string(m, opts \\ [])

Specs

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”
  • delimeter - default ".", sets the decimal delimeter. “1.23”
  • symbol = default true, sets whether to display the currency symbol or not.

Example:

iex> Money.to_string(Money.new(123456, :GBP))
"£1,234.56"
iex> Money.to_string(Money.new(123456, :EUR), separator: ".", delimeter: ",")
"€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"

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"
zero?(money)

Specs

zero?(t) :: boolean

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