# Elixir v1.4.4 Float View Source

Functions for working with floating point numbers.

# Link to this section Summary

## Functions

Rounds a float to the smallest integer greater than or equal to `num`

Rounds a float to the largest integer less than or equal to `num`

Parses a binary into a float

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 text representation of the given float

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

# Link to this section Functions

Link to this function ceil(number, precision \\ 0) View Source
`ceil(float, 0..15) :: float`

Rounds a float to the smallest integer greater than or equal to `num`.

`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``````
Link to this function floor(number, precision \\ 0) View Source
`floor(float, 0..15) :: float`

Rounds a float to the largest integer less than or equal to `num`.

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

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.

This function always returns a float. `Kernel.trunc/1` may be used instead to truncate the result to an integer afterwards.

## Examples

``````iex> Float.floor(34.25)
34.0
iex> Float.floor(-56.5)
-57.0
iex> Float.floor(34.259, 2)
34.25``````
Link to this function parse(binary) View Source
`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`, the `ArgumentError` exception is raised.

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

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

## Examples

``````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}``````
Link to this function round(float, precision \\ 0) View Source
`round(float, 0..15) :: 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.

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``````
Link to this function to_charlist(float) View Source
`to_charlist(float) :: charlist`

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

It uses the shortest representation according to algorithm described in “Printing Floating-Point Numbers Quickly and Accurately” in Proceedings of the SIGPLAN ‘96 Conference on Programming Language Design and Implementation.

## Examples

``````iex> Float.to_charlist(7.0)
'7.0'``````
Link to this function to_string(float) View Source
`to_string(float) :: String.t`

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

It uses the shortest representation according to algorithm described in “Printing Floating-Point Numbers Quickly and Accurately” in Proceedings of the SIGPLAN ‘96 Conference on Programming Language Design and Implementation.

## Examples

``````iex> Float.to_string(7.0)
"7.0"``````