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
Returns a Money
with the arithmetical absolute of the amount.
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.
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.
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.
Returns true if the amount of a Money
is greater than zero
Rounds a Money
struct using a given number of places. round
respects the
rounding mode within the current Decimal context.
Converts a Money
struct to a string representation
Returns true if the amount of a Money
struct is zero
Types
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}
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}
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.
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
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.
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
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}]
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
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}
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
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
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}
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}
@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 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
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
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}
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}
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")
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
- defaulttrue
, sets whether to display the currency symbol or not.:symbol_on_right
- defaultfalse
, display the currency symbol on the right of the number, eg: 123.45€:symbol_space
- defaultfalse
, add a space between currency symbol and number, eg: € 123,45 or 123.45 €:fractional_unit
- defaulttrue
, show the remaining units after the delimiter:strip_insignificant_zeros
- defaultfalse
, strip zeros after the delimiter:code
- defaultfalse
, append the currency code after the number:minus_sign_first
- defaulttrue
, display the minus sign before the currency symbol for negative values:strip_insignificant_fractional_unit
- defaultfalse
, 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"
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