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}

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}

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.

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

Example:

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

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.

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

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

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

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
iex> Money.equals?(Money.new(100, :USD), Money.new(100, :CAD))
false

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}

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}

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 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.cast(1_234.56), :USD)
{:ok, %Money{amount: 123456, currency: :USD}}

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" with currency :USD

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

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}

Converts a Money struct to a Decimal representation

Example:

iex> Money.to_decimal(Money.new(123456, :GBP))
#Decimal<1234.56>
iex> Money.to_decimal(Money.new(-123420, :EUR))
#Decimal<-1234.2>

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