Round a number to an arbitrary precision using one of several rounding algorithms.

Rounding algorithms are based on the definitions given in IEEE 754, but also include 2 additional options (effectively the complementary versions):

Arguments

• number is a float, integer or Decimal

• places is an integer number of places to round to

• mode is the rounding mode to be applied. The default is :half_even

Rounding algorithms

Directed roundings:

• :down - Round towards 0 (truncate), eg 10.9 rounds to 10.0

• :up - Round away from 0, eg 10.1 rounds to 11.0. (Non IEEE algorithm)

• :ceiling - Round toward +∞ - Also known as rounding up or ceiling

• :floor - Round toward -∞ - Also known as rounding down or floor

Round to nearest:

• :half_even - Round to nearest value, but in a tiebreak, round towards the nearest value with an even (zero) least significant bit, which occurs 50% of the time. This is the default for IEEE binary floating-point and the recommended value for decimal.

• :half_up - Round to nearest value, but in a tiebreak, round away from 0. This is the default algorithm for Erlang's Kernel.round/2

• :half_down - Round to nearest value, but in a tiebreak, round towards 0 (Non IEEE algorithm)

Notes

• When the number is a Decimal, the results are identical to Decimal.round/3 (delegates to Decimal in these cases)

• When the number is a float, places is 0 and mode is :half_up then the result is the same as Kernel.trunc/1

• The results of rounding for floats may not return the same result as Float.round/2. Float.round/2 operates on the binary representation. This implementation operates on a decimal representation.