Money v1.4.0 Money View Source

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

Link to this section Summary

Functions

Returns a Money with the arithmetical absolute of the amount

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

Link to this section Types

Link to this type t() View Source
t() :: %Money{amount: integer(), currency: atom()}

Link to this section 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}
Link to this function add(m, addend) View Source
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}
Link to this function compare(a, b) View Source
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
Link to this function divide(money, denominator) View Source
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}]
Link to this function equals?(a, b) View Source
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
Link to this function multiply(money, multiplier) View Source
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}

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}
Link to this function negative?(money) View Source
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

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}
Link to this function new(int, currency) View Source
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}
Link to this function parse!(value, currency \\ nil, opts \\ []) View Source

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"
Link to this function parse(value, currency \\ nil, opts \\ []) View Source
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}}
Link to this function positive?(money) View Source
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
Link to this function subtract(m, subtractend) View Source
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}
Link to this function to_string(money, opts \\ []) View Source
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"

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