Money v1.2.1 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
  symbol_on_right: false,  # position the symbol
  symbol_space: false      # add a space between symbol and number
  fractional_unit: false   # don’t display the remainder or the delimeter

Summary

Types

t()

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

compare(a, b)

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

divide(money, denominator)

Divides up Money by an amount

equals?(a, b)

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

subtract(m, subtractend)

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

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

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

Functions

abs(money)

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)

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)

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)

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)

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)

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}

neg(money)

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)

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)

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)

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 \\ [])

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

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)

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(money, opts \\ [])

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

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"
iex> Money.to_string(Money.new(123456, :EUR), fractional_unit: false)
"€1,234"

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)

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