@spec ceil(float(), precision_range()) :: float()

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 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
iex> Float.ceil(-0.01)
-0.0

@spec floor(float(), precision_range()) :: float()

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 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

@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

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

@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

@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}

@spec round(float(), precision_range()) :: float()

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. 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 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

@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 float-to-string conversion" in Proceedings of the SIGPLAN '2018 Conference on Programming Language Design and Implementation.

• For OTP < 24, it uses the algorithm presented in "Printing Floating-Point 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'

@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 float-to-string conversion" in Proceedings of the SIGPLAN '2018 Conference on Programming Language Design and Implementation.

• For OTP < 24, it uses the algorithm presented in "Printing Floating-Point 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"