On this page
Float
Functions for working with floatingpoint numbers.
For mathematical operations on top of floatingpoints, see Erlang's :math
module.
Kernel functions
There are functions related to floatingpoint numbers on the Kernel
module too. Here is a list of them:
Kernel.round/1
: rounds a number to the nearest integer.Kernel.trunc/1
: returns the integer part of a number.
Known issues
There are some very well known problems with floatingpoint numbers and arithmetic due to the fact most decimal fractions cannot be represented by a floatingpoint binary and most operations are not exact, but operate on approximations. Those issues are not specific to Elixir, they are a property of floating point representation itself.
For example, the numbers 0.1 and 0.01 are two of them, what means the result of squaring 0.1 does not give 0.01 neither the closest representable. Here is what happens in this case:
 The closest representable number to 0.1 is 0.1000000014
 The closest representable number to 0.01 is 0.0099999997
 Doing 0.1 * 0.1 should return 0.01, but because 0.1 is actually 0.1000000014, the result is 0.010000000000000002, and because this is not the closest representable number to 0.01, you'll get the wrong result for this operation
There are also other known problems like flooring or rounding numbers. See round/2
and floor/2
for more details about them.
To learn more about floatingpoint arithmetic visit:
Types
Functions
 ceil(number, precision \\ 0)

Rounds a float to the smallest integer greater than or equal to
num
.  floor(number, precision \\ 0)

Rounds a float to the largest number less than or equal to
num
.  max_finite()

Returns the maximum finite value for a float.
 min_finite()

Returns the minimum finite value for a float.
 parse(binary)

Parses a binary into a float.
 pow(base, exponent)

Computes
base
raised to power ofexponent
.  ratio(float)

Returns a pair of integers whose ratio is exactly equal to the original float and with a positive denominator.
 round(float, precision \\ 0)

Rounds a floatingpoint value to an arbitrary number of fractional digits (between 0 and 15).
 to_charlist(float)

Returns a charlist which corresponds to the shortest text representation of the given float.
 to_string(float)

Returns a binary which corresponds to the shortest text representation of the given float.
precision_range()Source
@type precision_range() :: 0..15
ceil(number, precision \\ 0)Source
@spec ceil(float(), precision_range()) :: float()
Rounds a float to the smallest integer greater than or equal to num
.
ceil/2
also accepts a precision to round a floatingpoint value down to an arbitrary number of fractional digits (between 0 and 15).
The operation is performed on the binary floating point, without a conversion to decimal.
The behaviour of ceil/2
for floats can be surprising. For example:
iex> Float.ceil(12.52, 2)
12.51
One may have expected it to ceil to 12.52. This is not a bug. Most decimal fractions cannot be represented as a binary floating point and therefore the number above is internally represented as 12.51999999, which explains the behaviour above.
This function always returns floats. Kernel.trunc/1
may be used instead to truncate the result to an integer afterwards.
Examples
iex> Float.ceil(34.25)
35.0
iex> Float.ceil(56.5)
56.0
iex> Float.ceil(34.251, 2)
34.26
floor(number, precision \\ 0)Source
@spec floor(float(), precision_range()) :: float()
Rounds a float to the largest number less than or equal to num
.
floor/2
also accepts a precision to round a floatingpoint value down to an arbitrary number of fractional digits (between 0 and 15). The operation is performed on the binary floating point, without a conversion to decimal.
This function always returns a float. Kernel.trunc/1
may be used instead to truncate the result to an integer afterwards.
Known issues
The behaviour of floor/2
for floats can be surprising. For example:
iex> Float.floor(12.52, 2)
12.51
One may have expected it to floor to 12.52. This is not a bug. Most decimal fractions cannot be represented as a binary floating point and therefore the number above is internally represented as 12.51999999, which explains the behaviour above.
Examples
iex> Float.floor(34.25)
34.0
iex> Float.floor(56.5)
57.0
iex> Float.floor(34.259, 2)
34.25
max_finite()Source
Returns the maximum finite value for a float.
Examples
iex> Float.max_finite()
1.7976931348623157e308
min_finite()Source
Returns the minimum finite value for a float.
Examples
iex> Float.min_finite()
1.7976931348623157e308
parse(binary)Source
@spec parse(binary()) :: {float(), binary()}  :error
Parses a binary into a float.
If successful, returns a tuple in the form of {float, remainder_of_binary}
; when the binary cannot be coerced into a valid float, the atom :error
is returned.
If the size of float exceeds the maximum size of 1.7976931348623157e+308
, :error
is returned even though the textual representation itself might be well formed.
If you want to convert a stringformatted float directly to a float, String.to_float/1
can be used instead.
Examples
iex> Float.parse("34")
{34.0, ""}
iex> Float.parse("34.25")
{34.25, ""}
iex> Float.parse("56.5xyz")
{56.5, "xyz"}
iex> Float.parse("pi")
:error
iex> Float.parse("1.7976931348623159e+308")
:error
pow(base, exponent)Source
@spec pow(float(), number()) :: float()
Computes base
raised to power of exponent
.
base
must be a float and exponent
can be any number. However, if a negative base and a fractional exponent are given, it raises ArithmeticError
.
It always returns a float. See Integer.pow/2
for exponentiation that returns integers.
Examples
iex> Float.pow(2.0, 0)
1.0
iex> Float.pow(2.0, 1)
2.0
iex> Float.pow(2.0, 10)
1024.0
iex> Float.pow(2.0, 1)
0.5
iex> Float.pow(2.0, 3)
0.125
iex> Float.pow(3.0, 1.5)
5.196152422706632
iex> Float.pow(2.0, 3)
8.0
iex> Float.pow(2.0, 4)
16.0
iex> Float.pow(1.0, 0.5)
** (ArithmeticError) bad argument in arithmetic expression
ratio(float)Source
@spec ratio(float()) :: {integer(), pos_integer()}
Returns a pair of integers whose ratio is exactly equal to the original float and with a positive denominator.
Examples
iex> Float.ratio(0.0)
{0, 1}
iex> Float.ratio(3.14)
{7070651414971679, 2251799813685248}
iex> Float.ratio(3.14)
{7070651414971679, 2251799813685248}
iex> Float.ratio(1.5)
{3, 2}
iex> Float.ratio(1.5)
{3, 2}
iex> Float.ratio(16.0)
{16, 1}
iex> Float.ratio(16.0)
{16, 1}
round(float, precision \\ 0)Source
@spec round(float(), precision_range()) :: float()
Rounds a floatingpoint value to an arbitrary number of fractional digits (between 0 and 15).
The rounding direction always ties to half up. The operation is performed on the binary floating point, without a conversion to decimal.
This function only accepts floats and always returns a float. Use Kernel.round/1
if you want a function that accepts both floats and integers and always returns an integer.
Known issues
The behaviour of round/2
for floats can be surprising. For example:
iex> Float.round(5.5675, 3)
5.567
One may have expected it to round to the half up 5.568. This is not a bug. Most decimal fractions cannot be represented as a binary floating point and therefore the number above is internally represented as 5.567499999, which explains the behaviour above. If you want exact rounding for decimals, you must use a decimal library. The behaviour above is also in accordance to reference implementations, such as "Correctly Rounded BinaryDecimal and DecimalBinary Conversions" by David M. Gay.
Examples
iex> Float.round(12.5)
13.0
iex> Float.round(5.5674, 3)
5.567
iex> Float.round(5.5675, 3)
5.567
iex> Float.round(5.5674, 3)
5.567
iex> Float.round(5.5675)
6.0
iex> Float.round(12.341444444444441, 15)
12.341444444444441
to_charlist(float)Source
@spec to_charlist(float()) :: charlist()
Returns a charlist which corresponds to the shortest text representation of the given float.
The underlying algorithm changes depending on the Erlang/OTP version:
For OTP >= 24, it uses the algorithm presented in "Ryū: fast floattostring conversion" in Proceedings of the SIGPLAN '2018 Conference on Programming Language Design and Implementation.
For OTP < 24, it uses the algorithm presented in "Printing FloatingPoint Numbers Quickly and Accurately" in Proceedings of the SIGPLAN '1996 Conference on Programming Language Design and Implementation.
For a configurable representation, use :erlang.float_to_list/2
.
Examples
iex> Float.to_charlist(7.0)
'7.0'
to_string(float)Source
@spec to_string(float()) :: String.t()
Returns a binary which corresponds to the shortest text representation of the given float.
The underlying algorithm changes depending on the Erlang/OTP version:
For OTP >= 24, it uses the algorithm presented in "Ryū: fast floattostring conversion" in Proceedings of the SIGPLAN '2018 Conference on Programming Language Design and Implementation.
For OTP < 24, it uses the algorithm presented in "Printing FloatingPoint Numbers Quickly and Accurately" in Proceedings of the SIGPLAN '1996 Conference on Programming Language Design and Implementation.
For a configurable representation, use :erlang.float_to_binary/2
.
Examples
iex> Float.to_string(7.0)
"7.0"
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.15.4/Float.html