Dinheiro v0.3.0 Dinheiro View Source

Link to this section Summary

Types

t()

Type that represents Dinheiro struct with:
:amount as integer that represents an amount.
:currency as atom that represents an ISO 4217 code.

Functions

compare(a, b)

Compares two Dinheiro structs with each other. They must each be of the same currency and then their value are compared.

compare!(a, b)

Compares two Dinheiro structs with each other. They must each be of the same currency and then their value are compared.

divide(a, b)

Divide a Dinheiro struct by a positive integer value

divide!(a, b)

Divide a Dinheiro struct by a positive integer value

equals?(arg1, arg2)

Retun true if two Dinheiro structs are equals.

is_dinheiro?(arg1)

Return if value is a Dinheiro struct.

multiply(a, b)

Return a new Dinheiro structs with value multiplied by other value. The first parameter must be a struct of Dinheiro.

multiply!(a, b)

Return a new Dinheiro structs with value multiplied by other value. The first parameter must be a struct of Dinheiro.

new(amount)

Create a new Dinheiro struct using a default currency. The default currency can be set in the system Mix config.

new(amount, currency)

Create a new Dinheiro struct.

new!(amount)

Create a new Dinheiro struct using a default currency. The default currency can be set in the system Mix config.

new!(amount, currency)

Create a new Dinheiro struct.

subtract(a, b)

Return a new Dinheiro structs with subtract of two values. The first parameter must be a struct of Dinheiro.

subtract!(a, b)

Return a new Dinheiro structs with subtract of two values. The first parameter must be a struct of Dinheiro.

sum(values)

Return a new Dinheiro structs with sum of a list of Dinheiro structs.

sum(a, b)

Return a new Dinheiro structs with sum of two values. The first parameter must be a struct of Dinheiro.

sum!(values)

Return a new Dinheiro structs with sum of a list of Dinheiro structs.

sum!(a, b)

Return a new Dinheiro structs with sum of two values. The first parameter must be a struct of Dinheiro.

to_float(from)

Return a float value from a Dinheiro structs.

to_float!(from)

Return a float value from a Dinheiro structs.

to_string(from, opts \\ [])

Return a formated string from a Dinheiro struct.

to_string!(from, opts \\ [])

Return a formated string from a Dinheiro struct.

Link to this section Types

t()

t() :: %Dinheiro{amount: integer(), currency: atom()}

Type that represents Dinheiro struct with:
:amount as integer that represents an amount.
:currency as atom that represents an ISO 4217 code.

Link to this section Functions

compare(a, b)

compare(t(), t()) :: {:ok, integer()} | {:error, String.t()}

Compares two Dinheiro structs with each other. They must each be of the same currency and then their value are compared.

Example:

iex> Dinheiro.compare(Dinheiro.new!(12345, :BRL), Dinheiro.new!(12345, :BRL))
{:ok, 0}
iex> Dinheiro.compare(Dinheiro.new!(12345, :BRL), Dinheiro.new!(12346, :BRL))
{:ok, -1}
iex> Dinheiro.compare(Dinheiro.new!(12346, :BRL), Dinheiro.new!(12345, :BRL))
{:ok, 1}
iex> Dinheiro.compare(Dinheiro.new!(12346, :USD), Dinheiro.new!(12346, :BRL))
{:error, "currency :BRL different of :USD"}

compare!(a, b)

compare!(t(), t()) :: integer()

Compares two Dinheiro structs with each other. They must each be of the same currency and then their value are compared.

Example:

iex> Dinheiro.compare!(Dinheiro.new!(12345, :BRL), Dinheiro.new!(12345, :BRL))
0
iex> Dinheiro.compare!(Dinheiro.new!(12345, :BRL), Dinheiro.new!(12346, :BRL))
-1
iex> Dinheiro.compare!(Dinheiro.new!(12346, :BRL), Dinheiro.new!(12345, :BRL))
1
iex> Dinheiro.compare!(Dinheiro.new!(12346, :USD), Dinheiro.new!(12346, :BRL))
** (ArgumentError) currency :BRL different of :USD

divide(a, b)

divide(t(), integer() | [integer()]) ::
  {:ok, [t()]} | {:error, String.t()}

Divide a Dinheiro struct by a positive integer value

Example:

iex> Dinheiro.divide(Dinheiro.new!(100, :BRL), 2)
{:ok, [%Dinheiro{amount: 5000, currency: :BRL}, %Dinheiro{amount: 5000, currency: :BRL}]}
iex> Dinheiro.divide(%Dinheiro{amount: 5050, currency: :NONE}, 2)
{:error, "'NONE' does not represent an ISO 4217 code"}

Divide a Dinheiro struct by an list of values that represents a division ratio.

Example:

iex> Dinheiro.divide(Dinheiro.new!(0.05, :BRL), [3, 7])
{:ok, [%Dinheiro{amount: 2, currency: :BRL}, %Dinheiro{amount: 3, currency: :BRL}]}

divide!(a, b)

divide!(t(), integer() | [integer()]) :: [t()]

Divide a Dinheiro struct by a positive integer value

Example:

iex> Dinheiro.divide!(Dinheiro.new!(100, :BRL), 2)
[%Dinheiro{amount: 5000, currency: :BRL}, %Dinheiro{amount: 5000, currency: :BRL}]
iex> Dinheiro.divide!(Dinheiro.new!(101, :BRL), 2)
[%Dinheiro{amount: 5050, currency: :BRL}, %Dinheiro{amount: 5050, currency: :BRL}]
iex> Dinheiro.divide!(%Dinheiro{amount: 5050, currency: :NONE}, 2)
** (ArgumentError) 'NONE' does not represent an ISO 4217 code

Divide a Dinheiro struct by an list of values that represents a division ratio.

Example:

iex> Dinheiro.divide!(Dinheiro.new!(0.05, :BRL), [3, 7])
[%Dinheiro{amount: 2, currency: :BRL}, %Dinheiro{amount: 3, currency: :BRL}]

equals?(arg1, arg2)

equals?(t(), t()) :: boolean()

Retun true if two Dinheiro structs are equals.

Example:

iex> Dinheiro.equals?(Dinheiro.new!(12345, :BRL), Dinheiro.new!(12345, :BRL))
true
iex> Dinheiro.equals?(Dinheiro.new!(12345, :BRL), Dinheiro.new!(12346, :BRL))
false
iex> Dinheiro.equals?(Dinheiro.new!(12345, :BRL), Dinheiro.new!(12345, :USD))
false

is_dinheiro?(arg1)

is_dinheiro?(any()) :: boolean()

Return if value is a Dinheiro struct.

Example:

iex> Dinheiro.is_dinheiro?(%Dinheiro{amount: 200, currency: :BRL})
true
iex> Dinheiro.is_dinheiro?(%{amount: 200, currency: :BRL})
false
iex> Dinheiro.is_dinheiro?(200)
false

multiply(a, b)

multiply(t(), integer() | float()) :: {:ok, t()} | {:error, String.t()}

Return a new Dinheiro structs with value multiplied by other value. The first parameter must be a struct of Dinheiro.

Example:

iex> Dinheiro.multiply(Dinheiro.new!(2, :BRL), 2)
{:ok, %Dinheiro{amount: 400, currency: :BRL}}
iex> Dinheiro.multiply(2, 2)
{:error, "value must be a Dinheiro struct"}

multiply!(a, b)

multiply!(t(), integer() | float()) :: t()

Return a new Dinheiro structs with value multiplied by other value. The first parameter must be a struct of Dinheiro.

Example:

iex> Dinheiro.multiply!(Dinheiro.new!(2, :BRL), 2)
%Dinheiro{amount: 400, currency: :BRL}
iex> Dinheiro.multiply!(Dinheiro.new!(5, :BRL), 2.5)
%Dinheiro{amount: 1250, currency: :BRL}
iex> Dinheiro.multiply!(Dinheiro.new!(4, :BRL), -2)
%Dinheiro{amount: -800, currency: :BRL}
iex> Dinheiro.multiply!(2, 2)
** (ArgumentError) value must be a Dinheiro struct

new(amount)

new(integer() | float()) :: {:ok, t()} | {:error, String.t()}

Create a new Dinheiro struct using a default currency. The default currency can be set in the system Mix config.

Example:

  iex> Application.put_env(:ex_dinheiro, :default_currency, :BRL)
  iex> Dinheiro.new(12345)
  {:ok, %Dinheiro{amount: 1234500, currency: :BRL}}
  iex> Dinheiro.new("1")
  {:error, "value '1' must be integer or float"}
  iex> Application.delete_env(:ex_dinheiro, :default_currency)
  iex> Dinheiro.new(12345)
  {:error, "you must set a default value in your application config :ex_dinheiro, default_currency"}

new(amount, currency)

new(integer() | float(), atom() | String.t()) ::
  {:ok, t()} | {:error, String.t()}

Create a new Dinheiro struct.

Example:

iex> Dinheiro.new(12345, :BRL)
{:ok, %Dinheiro{amount: 1234500, currency: :BRL}}
iex> Dinheiro.new("1", :BRL)
{:error, "value '1' must be integer or float"}
iex> Dinheiro.new(12345, :XBT)
{:error, "'XBT' does not represent an ISO 4217 code"}
iex> currencies = %{ XBT: %Moeda{name: "Bitcoin", symbol: '฿', alpha_code: "XBT", num_code: 0, exponent: 8} }
iex> Application.put_env(:ex_dinheiro, :unofficial_currencies, currencies)
iex> Dinheiro.new(123.45, :XBT)
{:ok, %Dinheiro{amount: 12345000000, currency: :XBT}}

new!(amount)

new!(integer() | float()) :: t()

Create a new Dinheiro struct using a default currency. The default currency can be set in the system Mix config.

Example:

  iex> Application.put_env(:ex_dinheiro, :default_currency, :BRL)
  iex> Dinheiro.new!(12345)
  %Dinheiro{amount: 1234500, currency: :BRL}
  iex> Dinheiro.new!(123.45)
  %Dinheiro{amount: 12345, currency: :BRL}
  iex> Dinheiro.new!("1")
  ** (ArgumentError) value '1' must be integer or float

new!(amount, currency)

new!(integer() | float(), atom() | String.t()) :: t()

Create a new Dinheiro struct.

Example:

iex> Dinheiro.new!(12345, :BRL)
%Dinheiro{amount: 1234500, currency: :BRL}
iex> Dinheiro.new!(12345, "BRL")
%Dinheiro{amount: 1234500, currency: :BRL}
iex> Dinheiro.new!(123.45, :BRL)
%Dinheiro{amount: 12345, currency: :BRL}
iex> Dinheiro.new!(123.45, "BRL")
%Dinheiro{amount: 12345, currency: :BRL}
iex> Dinheiro.new!(12345, :NONE)
** (ArgumentError) 'NONE' does not represent an ISO 4217 code

Is possible to work with no official ISO currency code adding it in the system Mix config.

Examples

iex> Moeda.find(:XBT)
{:error, "'XBT' does not represent an ISO 4217 code"}
iex> currencies = %{ XBT: %Moeda{name: "Bitcoin", symbol: '฿', alpha_code: "XBT", num_code: 0, exponent: 8} }
iex> Application.put_env(:ex_dinheiro, :unofficial_currencies, currencies)
iex> Dinheiro.new!(123.45, :XBT)
%Dinheiro{amount: 12345000000, currency: :XBT}

subtract(a, b)

subtract(t(), t() | integer() | float()) ::
  {:ok, t()} | {:error, String.t()}

Return a new Dinheiro structs with subtract of two values. The first parameter must be a struct of Dinheiro.

Example:

iex> Dinheiro.subtract(Dinheiro.new!(2, :BRL), Dinheiro.new!(1, :BRL))
{:ok, %Dinheiro{amount: 100, currency: :BRL}}
iex> Dinheiro.subtract(%Dinheiro{amount: 100, currency: :NONE}, 2)
{:error, "'NONE' does not represent an ISO 4217 code"}
iex> Dinheiro.subtract(2, 2)
{:error, "value must be a Dinheiro struct"}
iex> Dinheiro.subtract(Dinheiro.new!(2, :BRL), "1")
{:error, "value '1' must be integer or float"}
iex> Dinheiro.subtract(%Dinheiro{amount: 100, currency: :NONE}, %Dinheiro{amount: 100, currency: :NONE})
{:error, "'NONE' does not represent an ISO 4217 code"}

subtract!(a, b)

subtract!(t(), t() | integer() | float()) :: t()

Return a new Dinheiro structs with subtract of two values. The first parameter must be a struct of Dinheiro.

Example:

iex> Dinheiro.subtract!(Dinheiro.new!(2, :BRL), Dinheiro.new!(1, :BRL))
%Dinheiro{amount: 100, currency: :BRL}
iex> Dinheiro.subtract!(Dinheiro.new!(4, :BRL), 2)
%Dinheiro{amount: 200, currency: :BRL}
iex> Dinheiro.subtract!(Dinheiro.new!(5, :BRL), 2.5)
%Dinheiro{amount: 250, currency: :BRL}
iex> Dinheiro.subtract!(Dinheiro.new!(4, :BRL), -2)
%Dinheiro{amount: 600, currency: :BRL}
iex> Dinheiro.subtract!(%Dinheiro{amount: 100, currency: :NONE}, %Dinheiro{amount: 100, currency: :NONE})
** (ArgumentError) 'NONE' does not represent an ISO 4217 code

sum(values)

sum([t()]) :: {:ok, t()} | {:error, String.t()}

Return a new Dinheiro structs with sum of a list of Dinheiro structs.

Example:

iex> a = Dinheiro.new!(1, :BRL)
iex> b = Dinheiro.new!(1, :BRL)
iex> c = Dinheiro.new!(1, :BRL)
iex> d = Dinheiro.new!(1, :BRL)
iex> values = [a, b, c, d]
iex> Dinheiro.sum(values)
{:ok, %Dinheiro{amount: 400, currency: :BRL}}

The first item currency will be the result currency.

Example:

iex> a = Dinheiro.new!(1, :BRL)
iex> b = Dinheiro.new!(1, :USD)
iex> c = Dinheiro.new!(1, :USD)
iex> d = Dinheiro.new!(1, :USD)
iex> e = Dinheiro.new!(1, :USD)
iex> Dinheiro.sum([a, b, c, d, e])
{:error, "currency :USD different of :BRL"}
iex> Dinheiro.sum([b, a, c, d, e])
{:error, "currency :BRL different of :USD"}

sum(a, b)

sum(t(), t() | integer() | float()) ::
  {:ok, t()} | {:error, String.t()}

Return a new Dinheiro structs with sum of two values. The first parameter must be a struct of Dinheiro.

Example:

iex> Dinheiro.sum(Dinheiro.new!(2, :BRL), Dinheiro.new!(1, :BRL))
{:ok, %Dinheiro{amount: 300, currency: :BRL}}
iex> Dinheiro.sum(%Dinheiro{amount: 100, currency: :NONE}, 2)
{:error, "'NONE' does not represent an ISO 4217 code"}
iex> Dinheiro.sum(2, 2)
{:error, "value must be a Dinheiro struct"}
iex> Dinheiro.sum(Dinheiro.new!(2, :BRL), "1")
{:error, "value '1' must be integer or float"}
iex> Dinheiro.sum(%Dinheiro{amount: 100, currency: :NONE}, %Dinheiro{amount: 100, currency: :NONE})
{:error, "'NONE' does not represent an ISO 4217 code"}

sum!(values)

sum!([t()]) :: t()

Return a new Dinheiro structs with sum of a list of Dinheiro structs.

Example:

iex> a = Dinheiro.new!(1, :BRL)
iex> b = Dinheiro.new!(1, :BRL)
iex> c = Dinheiro.new!(1, :BRL)
iex> d = Dinheiro.new!(1, :BRL)
iex> values = [a, b, c, d]
iex> Dinheiro.sum!(values)
%Dinheiro{amount: 400, currency: :BRL}

The first item currency will be the result currency.

Example:

iex> a = Dinheiro.new!(1, :BRL)
iex> b = Dinheiro.new!(1, :USD)
iex> c = Dinheiro.new!(1, :USD)
iex> d = Dinheiro.new!(1, :USD)
iex> e = Dinheiro.new!(1, :USD)
iex> values = [a, b, c, d, e]
iex> Dinheiro.sum!(values)
** (ArgumentError) currency :USD different of :BRL

sum!(a, b)

sum!(t(), t() | integer() | float()) :: t()

Return a new Dinheiro structs with sum of two values. The first parameter must be a struct of Dinheiro.

Example:

iex> Dinheiro.sum!(Dinheiro.new!(1, :BRL), Dinheiro.new!(1, :BRL))
%Dinheiro{amount: 200, currency: :BRL}
iex> Dinheiro.sum!(Dinheiro.new!(1, :BRL), 2)
%Dinheiro{amount: 300, currency: :BRL}
iex> Dinheiro.sum!(Dinheiro.new!(1, :BRL), 2.5)
%Dinheiro{amount: 350, currency: :BRL}
iex> Dinheiro.sum!(Dinheiro.new!(2, :BRL), -1)
%Dinheiro{amount: 100, currency: :BRL}
iex> Dinheiro.sum!(Dinheiro.new!(2, :BRL), "1")
** (ArgumentError) value '1' must be integer or float

to_float(from)

to_float(t()) :: {:ok, float()} | {:error, String.t()}

Return a float value from a Dinheiro structs.

Example:

iex> Dinheiro.to_float(%Dinheiro{amount: 200, currency: :BRL})
{:ok, 2.0}
iex> Dinheiro.to_float(%Dinheiro{amount: 200, currency: :NONE})
{:error, "'NONE' does not represent an ISO 4217 code"}

to_float!(from)

to_float!(t()) :: float()

Return a float value from a Dinheiro structs.

Example:

iex> Dinheiro.to_float!(%Dinheiro{amount: 200, currency: :BRL})
2.0
iex> Dinheiro.to_float!(Dinheiro.new!(50.5, :BRL))
50.5
iex> Dinheiro.to_float!(Dinheiro.new!(-4, :BRL))
-4.0
iex> Dinheiro.to_float!(%Dinheiro{amount: 200, currency: :NONE})
** (ArgumentError) 'NONE' does not represent an ISO 4217 code

to_string(from, opts \\ [])

to_string(t(), Keywords.t()) :: {:ok, String.t()} | {:error, String.t()}

Return a formated string from a Dinheiro struct.

Example:

iex> Dinheiro.to_string(%Dinheiro{amount: 200, currency: :BRL})
{:ok, "R$ 2,00"}
iex> Dinheiro.to_string(%Dinheiro{amount: 200, currency: :NONE})
{:error, "'NONE' does not represent an ISO 4217 code"}

to_string!(from, opts \\ [])

to_string!(t(), Keywords.t()) :: String.t()

Return a formated string from a Dinheiro struct.

Example:

iex> Dinheiro.to_string!(%Dinheiro{amount: 200, currency: :BRL})
"R$ 2,00"
iex> Dinheiro.to_string!(Dinheiro.new!(50.5, :BRL))
"R$ 50,50"
iex> Dinheiro.to_string!(Dinheiro.new!(-4, :BRL))
"R$ -4,00"
iex> Dinheiro.to_string!(%Dinheiro{amount: 200, currency: :NONE})
** (ArgumentError) 'NONE' does not represent an ISO 4217 code

Using options-style parameters you can change the behavior of the function.

thousand_separator - default ".", sets the thousand separator.
decimal_separator - default ",", sets the decimal separator.
display_currency_symbol - default true, put to false to hide de currency symbol.
display_currency_code - default false, put to true to display de currency ISO 4217 code.

Exemples

iex> Dinheiro.to_string!(Dinheiro.new!(1000.5, :USD), thousand_separator: ",", decimal_separator: ".")
"$ 1,000.50"
iex> Dinheiro.to_string!(Dinheiro.new!(1000.5, :USD), display_currency_symbol: false)
"1.000,50"
iex> Dinheiro.to_string!(Dinheiro.new!(1000.5, :USD), display_currency_code: true)
"$ 1.000,50 USD"
iex> Dinheiro.to_string!(Dinheiro.new!(1000.5, :USD), display_currency_code: true, display_currency_symbol: false)
"1.000,50 USD"

The default values also can be set in the system Mix config.

Example:

iex> Application.put_env(:ex_dinheiro, :thousand_separator, ",")
iex> Application.put_env(:ex_dinheiro, :decimal_separator, ".")
iex> Dinheiro.to_string!(Dinheiro.new!(1000.5, :USD))
"$ 1,000.50"
iex> Application.put_env(:ex_dinheiro, :display_currency_symbol, false)
iex> Dinheiro.to_string!(Dinheiro.new!(5000.5, :USD))
"5,000.50"
iex> Application.put_env(:ex_dinheiro, :display_currency_code, true)
iex> Dinheiro.to_string!(Dinheiro.new!(10000.0, :USD))
"10,000.00 USD"

The options-style parameters override values in the system Mix config.

Example:

iex> Application.put_env(:ex_dinheiro, :thousand_separator, ",")
iex> Application.put_env(:ex_dinheiro, :decimal_separator, ".")
iex> Dinheiro.to_string!(Dinheiro.new!(1000.5, :USD))
"$ 1,000.50"
iex> Dinheiro.to_string!(Dinheiro.new!(1000.5, :BRL), thousand_separator: ".", decimal_separator: ",")
"R$ 1.000,50"

Is possible to override some official ISO currency code adding it in the system Mix config.

Examples

iex> Dinheiro.to_string!(Dinheiro.new!(12_345_678.9, :BRL))
"R$ 12.345.678,90"
iex> Dinheiro.to_string!(Dinheiro.new!(12_345_678.9, :USD))
"$ 12.345.678,90"
iex> Dinheiro.to_string!(%Dinheiro{amount: 200, currency: :XBT})
** (ArgumentError) 'XBT' does not represent an ISO 4217 code
iex> real = %Moeda{name: "Moeda do Brasil", symbol: 'BR$', alpha_code: "BRL", num_code: 986, exponent: 4}
%Moeda{name: "Moeda do Brasil", symbol: 'BR$', alpha_code: "BRL", num_code: 986, exponent: 4}
iex> dollar = %Moeda{name: "Moeda do EUA", symbol: 'US$', alpha_code: "USD", num_code: 840, exponent: 3}
%Moeda{name: "Moeda do EUA", symbol: 'US$', alpha_code: "USD", num_code: 840, exponent: 3}
iex> bitcoin = %Moeda{name: "Bitcoin", symbol: '฿', alpha_code: "XBT", num_code: 0, exponent: 8}
%Moeda{name: "Bitcoin", symbol: '฿', alpha_code: "XBT", num_code: 0, exponent: 8}
iex> currencies = %{ BRL: real, USD: dollar, XBT: bitcoin }
iex> Application.put_env(:ex_dinheiro, :unofficial_currencies, currencies)
iex> Dinheiro.to_string!(Dinheiro.new!(12_345_678.9, :BRL))
"BR$ 12.345.678,9000"
iex> Dinheiro.to_string!(Dinheiro.new!(12_345_678.9, :usd))
"US$ 12.345.678,900"
iex> Dinheiro.to_string!(Dinheiro.new!(12_345_678.9, "XBT"))
"฿ 12.345.678,90000000"