Dinheiro v0.1.7 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 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 two values. The first parameter must be a struct of Dinheiro

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 must be the same as :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 must be the same as :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 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, "the first param 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) the first param 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: '฿', iso_code: "XBT", country_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: '฿', iso_code: "XBT", country_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, "the first param 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(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, "the first param 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!(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$', iso_code: "BRL", country_code: 986, exponent: 4}
%Moeda{name: "Moeda do Brasil", symbol: 'BR$', iso_code: "BRL", country_code: 986, exponent: 4}
iex> dollar = %Moeda{name: "Moeda do EUA", symbol: 'US$', iso_code: "USD", country_code: 840, exponent: 3}
%Moeda{name: "Moeda do EUA", symbol: 'US$', iso_code: "USD", country_code: 840, exponent: 3}
iex> bitcoin = %Moeda{name: "Bitcoin", symbol: '฿', iso_code: "XBT", country_code: 0, exponent: 8}
%Moeda{name: "Bitcoin", symbol: '฿', iso_code: "XBT", country_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"