View Source Money (Money v1.12.4)
Defines a Money struct along with convenience methods for working with currencies.
examples
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
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 zerosLink to this section 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
Link to this section Types
Link to this section Functions
Returns a Money with the arithmetical absolute of the amount.
examples
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
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
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))
:gtCompares 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
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))
1Divides up Money by an amount
examples
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
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))
falseMultiplies a Money by an amount
examples
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
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
Examples
iex> Money.negative?(Money.new(0, :USD))
false
iex> Money.negative?(Money.new(1, :USD))
false
iex> Money.negative?(Money.new(-1, :USD))
trueCreate a new Money struct using a default currency.
The default currency can be set in the system Mix config.
config
Config
config :money,
default_currency: :USD
examples
Examples
Money.new(123)
%Money{amount: 123, currency: :USD}Create a new Money struct from currency sub-units (cents)
examples
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
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
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 :USDReturns true if the amount of a Money is greater than zero
examples
Examples
iex> Money.positive?(Money.new(0, :USD))
false
iex> Money.positive?(Money.new(1, :USD))
true
iex> Money.positive?(Money.new(-1, :USD))
falseRounds 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
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
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
Examples
iex> Money.to_decimal(Money.new(123456, :GBP))
#Decimal<1234.56>
iex> Money.to_decimal(Money.new(-123420, :EUR))
#Decimal<-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
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-1
Examples
iex> "Total: #{Money.new(100_00, :USD)}"
"Total: $100.00"Returns true if the amount of a Money struct is zero
examples
Examples
iex> Money.zero?(Money.new(0, :USD))
true
iex> Money.zero?(Money.new(1, :USD))
false