Dinheiro v0.2.1 Dinheiro View Source
Link to this section Summary
Types
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
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 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
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
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"}
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 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 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}]
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
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
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"}
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
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"}
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
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}
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"}
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
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"}
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"}
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
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
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"}
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
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"}
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
- defaulttrue
, put tofalse
to hide de currency symbol.display_currency_code
- defaultfalse
, put totrue
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"