Float — Elixir v1.18.3 (original) (raw)

Functions for working with floating-point numbers.

For mathematical operations on top of floating-points, see Erlang's :math module.

Kernel functions

There are functions related to floating-point numbers on the Kernel module too. Here is a list of them:

Known issues

There are some very well known problems with floating-point numbers and arithmetic due to the fact most decimal fractions cannot be represented by a floating-point 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:

There are also other known problems like flooring or rounding numbers. Seeround/2 and floor/2 for more details about them.

To learn more about floating-point arithmetic visit:

Summary

Functions

Rounds a float to the smallest float greater than or equal to number.

Rounds a float to the largest float less than or equal to number.

Returns the maximum finite value for a float.

Returns the minimum finite value for a float.

Parses a binary into a float.

Computes base raised to power of exponent.

Returns a pair of integers whose ratio is exactly equal to the original float and with a positive denominator.

Rounds a floating-point value to an arbitrary number of fractional digits (between 0 and 15).

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

Returns a binary which corresponds to the shortest text representation of the given float.

Types

@type precision_range() :: 0..15

Functions

Rounds a float to the smallest float greater than or equal to number.

ceil/2 also accepts a precision to round a floating-point 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 behavior 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 behavior 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
iex> Float.ceil(-0.01)
-0.0

Rounds a float to the largest float less than or equal to number.

floor/2 also accepts a precision to round a floating-point 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 behavior 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 behavior above.

Examples

iex> Float.floor(34.25)
34.0
iex> Float.floor(-56.5)
-57.0
iex> Float.floor(34.259, 2)
34.25

@spec max_finite() :: float()

Returns the maximum finite value for a float.

Examples

iex> Float.max_finite()
1.7976931348623157e308

@spec min_finite() :: float()

Returns the minimum finite value for a float.

Examples

iex> Float.min_finite()
-1.7976931348623157e308

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 string-formatted 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(".12")
:error
iex> Float.parse("pi")
:error
iex> Float.parse("1.7976931348623159e+308")
:error

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

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}

Rounds a floating-point 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. UseKernel.round/1 if you want a function that accepts both floats and integers and always returns an integer.

Known issues

The behavior 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 behavior above. If you want exact rounding for decimals, you must use a decimal library. The behavior above is also in accordance to reference implementations, such as "Correctly Rounded Binary-Decimal and Decimal-Binary 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
iex> Float.round(-0.01)
-0.0

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

It uses the algorithm presented in "Ryū: fast float-to-string conversion" in Proceedings of the SIGPLAN '2018 Conference on Programming Language Design and Implementation.

For a configurable representation, use :erlang.float_to_list/2.

Inlined by the compiler.

Examples

iex> Float.to_charlist(7.0)
~c"7.0"

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 a configurable representation, use :erlang.float_to_binary/2.

Inlined by the compiler.

Examples

iex> Float.to_string(7.0)
"7.0"