Monetized v0.5.0 Monetized.Money

Defines the money struct and functions to handle it.

Also defines Money Ecto.Type.

Although we’re able to override any configuration when calling functions that create/handle money, it is possible to change any of the default values seen below, through config.

Below are the configuration options.

Examples

config :monetized, config: [
  delimiter: ",",
  separator: ".",
  currency: "USD",
  format: "%c %n%s%d"
]

Summary

Types

t()

A money struct containing the a Decimal tha holds the amount and the currency

Functions

cast(money)

Casts the given value to money

dump(money)

Converts an Monetized.Money into a string for saving to the db. ie: “100.50 EUR”

from_decimal(decimal, options \\ [])

Creates a money struct from a Decimal

from_float(amount, options \\ [])

Creates a money struct from a float value

from_integer(amount, options \\ [])

Creates a money struct from a integer value

from_string(amount, options \\ [])

Creates a money struct from a string value

load(m)

Converts a string as saved to the db into a Monetized.Money struct

make(amount, options \\ [])

Creates a money struct from any of the supported types for amount

to_string(money, options \\ [])

Returns a string representation of the given money

type()

The Ecto primitive type

zero(options \\ [])

Creates a money struct with 0 value

Types

t :: %Monetized.Money{currency: String.t, value: Decimal.t}

A money struct containing the a Decimal tha holds the amount and the currency.

Functions

cast(money)

Casts the given value to money.

It supports:

A string (if currency not relevant).
A float (if currency not relevant).
An Decimal struct (if currency not relevant).
An integer (if currency not relevant).
A map with :value and :currency keys.
A map with “value” and “currency” keys.
An Monetized.Money struct.

dump(money)

Converts an Monetized.Money into a string for saving to the db. ie: “100.50 EUR”

from_decimal(decimal, options \\ [])

Specs

from_decimal(Decimal, list) :: t

Creates a money struct from a Decimal.

It uses the default currency (“USD”) if one isn’t configured.

Passing currency in the options will make it use that despite of configured default.

Examples

iex> Decimal.new(100.00) |> Monetized.Money.from_decimal([currency: "EUR"])
#Money<100.00EUR>

iex> Decimal.new(150.52) |> Monetized.Money.from_decimal
#Money<150.52>

iex> Decimal.new("300.25") |> Monetized.Money.from_decimal
#Money<300.25>

from_float(amount, options \\ [])

Specs

from_float(float, list) :: t

Creates a money struct from a float value.

Passing currency in the options will make it use that despite of configured default.

Examples

iex> Monetized.Money.from_float(100.00, [currency: "EUR"])
#Money<100.00EUR>

iex> Monetized.Money.from_float(150.52)
#Money<150.52>

# iex> Monetized.Money.from_float(20.50)
#Money<20.50>

from_integer(amount, options \\ [])

Specs

from_integer(integer, list) :: t

Creates a money struct from a integer value.

Passing currency in the options will make it use that despite of configured default.

Examples

iex> Monetized.Money.from_integer(152, [currency: "GBP"])
#Money<152.00GBP>

iex> Monetized.Money.from_integer(100_000, [currency: "GBP"])
#Money<100000.00GBP>

iex> Monetized.Money.from_integer(-100, [currency: "GBP"])
#Money<-100.00GBP>

from_string(amount, options \\ [])

Specs

from_string(String.t, list) :: t

Creates a money struct from a string value.

Passing currency in the options will make it use that despite of configured default.

Examples

iex> Monetized.Money.from_string("GBP 10.52")
#Money<10.52GBP>

iex> Monetized.Money.from_string("€ 100")
#Money<100.00EUR>

iex> Monetized.Money.from_string("100.00", [currency: "EUR"])
#Money<100.00EUR>

iex> Monetized.Money.from_string("$50")
#Money<50.00USD>

iex> Monetized.Money.from_string("1,000,000 EUR")
#Money<1000000.00EUR>

iex> Monetized.Money.from_string("200", currency: "THB")
#Money<200.00THB>

load(m)

Converts a string as saved to the db into a Monetized.Money struct.

make(amount, options \\ [])

Specs

make(integer | float | String.t | Decimal, list) :: t

Creates a money struct from any of the supported types for amount.

If a string is given with either the currency key/code (ie “USD”) or the symbol present, that currency will be assumed.

Passing currency in the options will make it use that despite of configured, or assumed from string.

Examples

iex> Monetized.Money.make("20150.25 EUR")
#Money<20150.25EUR>

iex> Monetized.Money.make(20150.25, [currency: "EUR"])
#Money<20150.25EUR>

iex> Decimal.new("100.50") |> Monetized.Money.make
#Money<100.50>

iex> Monetized.Money.make("£ 100")
#Money<100.00GBP>

# currency in options takes precedence
iex> Monetized.Money.make("€ 50", [currency: "USD"])
#Money<50.00USD>

to_string(money, options \\ [])

Specs

to_string(t, list) :: String.t

Returns a string representation of the given money.

Examples

iex> money = Monetized.Money.make("£ 20150.25")
...> Monetized.Money.to_string(money, [currency_symbol: true])
"£ 20,150.25"

# Ignores currency as there isn't one
iex> money = Monetized.Money.make(999999999)
...> Monetized.Money.to_string(money, [delimiter: " ", separator: " ", currency_symbol: true])
"999 999 999 00"

iex> money = Monetized.Money.make(100_000_000, [currency: "USD"])
...> Monetized.Money.to_string(money, [format: "%n%s%d %cs", currency_symbol: true])
"100,000,000.00 $"

iex> money = Monetized.Money.make(-99.50, [currency: "USD"])
...> Monetized.Money.to_string(money, [currency_symbol: true])
"$ -99.50"

iex> money = Monetized.Money.make("100.50 EUR")
...> Monetized.Money.to_string(money, [currency_code: true])
"100.50 EUR"

iex> money = Monetized.Money.make(Decimal.new("10"))
...> Monetized.Money.to_string(money)
"10.00"

iex> money = Monetized.Money.make(Decimal.new("10"), currency: "USD")
...> Monetized.Money.to_string(money, currency_symbol: true)
"$ 10.00"

iex> money = Monetized.Money.make(Decimal.new(".005"), currency: "USD")
...> Monetized.Money.to_string(money, currency_symbol: true)
"$ 0.01"

type()

The Ecto primitive type.

zero(options \\ [])

Creates a money struct with 0 value.

Useful for setting a default value of “0.00”.

Examples

iex> Monetized.Money.zero
#Money<0.00>

iex> Monetized.Money.zero([currency: "GBP"])
#Money<0.00GBP>