Dinheiro v0.3.0 Dinheiro View Source

Build Status Coverage Status

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

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

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

Divide a Dinheiro struct by a positive integer value

Divide a Dinheiro struct by a positive integer value

Retun true if two Dinheiro structs are equals.

Return if value is a Dinheiro struct.

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

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

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

Create a new Dinheiro struct.

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

Create a new Dinheiro struct.

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

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

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

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

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

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

Return a float value from a Dinheiro structs.

Return a float value from a Dinheiro structs.

Return a formated string from a Dinheiro struct.

Return a formated string from a Dinheiro struct.

Link to this section Types

Link to this type

t()

View Source
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

Link to this function

compare(a, b)

View Source
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"}
Link to this function

compare!(a, b)

View Source
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
Link to this function

divide(a, b)

View Source
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}]}
Link to this function

divide!(a, b)

View Source
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}]
Link to this function

equals?(arg1, arg2)

View Source
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
Link to this function

is_dinheiro?(arg1)

View Source
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
Link to this function

multiply(a, b)

View Source
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"}
Link to this function

multiply!(a, b)

View Source
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
Link to this function

new(amount)

View Source
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"}
Link to this function

new(amount, currency)

View Source
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}}

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
Link to this function

new!(amount, currency)

View Source
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}
Link to this function

subtract(a, b)

View Source
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"}
Link to this function

subtract!(a, b)

View Source
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
Link to this function

sum(values)

View Source
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"}
Link to this function

sum(a, b)

View Source
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"}
Link to this function

sum!(values)

View Source
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
Link to this function

sum!(a, b)

View Source
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
Link to this function

to_float(from)

View Source
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"}
Link to this function

to_float!(from)

View Source
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
Link to this function

to_string(from, opts \\ [])

View Source
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"}
Link to this function

to_string!(from, opts \\ [])

View Source
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"