Numbers (numbers v5.2.4)
Allows you to use arithmetical operations on any type that implements the proper protocols.
For each arithmetical operation, a different protocol is used so that types for which only a subset of these operations makes sense can still work with those.
Basic Usage
Usually, Numbers
is used in another module by using
alias Numbers, as: N
, followed by calling the functions using
this aliased but still descriptive syntax:
total_price = N.mult(N.add(price, fee), vat)
Because Numbers
dispatches based on protocol definitions,
you only need to swap what kind of arguments are used
to change the type of the result.
Overloaded Operators
As explicit opt-in functionality, Numbers
will add overloaded
operators to your module, if you write use Numbers, overload_operators: true
This will alter a + b
, a - b
, a * b
, a / b
, -a
and abs(a)
to
dispatch to the corresponding functions in the Numbers
module.
Do note that these overloaded operator versions are not allowed in guard tests, which is why this functionality is only provided as an opt-in option to use when an algorithm would be too unreadable without it.
Examples:
Using built-in numbers:
iex> alias Numbers, as: N
iex> N.add(1, 2)
3
iex> N.mult(3,5)
15
iex> N.mult(1.5, 100)
150.0
Using Decimals: (requires the Decimal library.)
iex> alias Numbers, as: N
iex> d = Decimal.new(2)
iex> N.div(d, 10)
#Decimal<0.2>
iex> small_number = N.div(d, 1234)
#Decimal<0.001620745542949756888168557536>
iex> N.pow(small_number, 100)
#Decimal<9.364478495445313580679473524E-280>
Defining your own Numbers implementations
See Numbers.Protocols
for a full explanation on how to do this.
Link to this section Summary
Functions
The absolute value of a number.
Adds two Numeric a
and b
together.
Divides the Numeric a
by b
.
Unary minus. Returns the negation of the number.
Multiplies the Numeric a
with the Numeric b
Power function: computes base^exponent
,
where base
is Numeric,
and exponent
has to be an integer.
Subtracts the Numeric b
from the Numeric a
.
Convert the custom Numeric struct to the built-in float datatype.
Link to this section Types
Specs
t() :: any()
Link to this section Functions
abs(num)
Specs
The absolute value of a number.
Depends on an implementation existing of Numbers.Protocols.Absolute
add(a, b)
Specs
Adds two Numeric a
and b
together.
Depends on an implementation existing of Numbers.Protocol.Addition
add_id(num)
div(a, b)
Specs
Divides the Numeric a
by b
.
Note that this is a supposed to be a full (non-truncated) division; no rounding or truncation is supposed to happen, even when calculating with integers.
Depends on an implementation existing of Numbers.Protocol.Division
minus(num)
Specs
Unary minus. Returns the negation of the number.
Depends on an implementation existing of Numbers.Protocols.Minus
mult(a, b)
Specs
Multiplies the Numeric a
with the Numeric b
Depends on an implementation existing of Numbers.Protocol.Multiplication
mult_id(num)
pow(num, power)
Specs
pow(t(), non_neg_integer()) :: t()
Power function: computes base^exponent
,
where base
is Numeric,
and exponent
has to be an integer.
(This means that it is impossible to calculate roots by using this function.)
Depends on an implementation existing of Numbers.Protocol.Exponentiation
sub(a, b)
Specs
Subtracts the Numeric b
from the Numeric a
.
Depends on an implementation existing of Numbers.Protocol.Subtraction
to_float(num)
Specs
Convert the custom Numeric struct to the built-in float datatype.
This operation might be lossy, losing precision in the process.