These functions implement the industry standard IEEE 754:
round_ties_to_even()rounds to the nearest value. If both are at equal distance, it tends to round to the even number (seebase::round()for details).round_ties_to_away()rounds to the nearest value. If both are at equal distance, it rounds to the number with the greater absolute value, i.e., the number that is further away from zero.round_toward_positive()always rounds to the greater of the two nearest values. This is like ceiling at a given number of decimal places.round_toward_negative()always rounds to the lesser of the two nearest values. This is like flooring at a given number of decimal places.round_toward_zero()always rounds to the number with the lower absolute value, i.e., the number that is closer to zero. This is like truncation at a given number of decimal places.
Usage
round_ties_to_even(x, digits = 0L)
round_ties_to_away(x, digits = 0L)
round_toward_positive(x, digits = 0L)
round_toward_negative(x, digits = 0L)
round_toward_zero(x, digits = 0L)Details
The function names follow the official standard except for case conventions (IEEE 2019, pp. 27f.; the Wikipedia page is more accessible but uses slightly different names).
Internally, these functions are just wrappers around other roundwork
functions as well as base::round(). They are presented here for easy
compliance with the IEEE 754 standard in R. Each of them has an equivalent
elsewhere in the package, and the results are identical:
| IEEE 754 name | Equivalent |
round_ties_to_even() | base::round() |
round_ties_to_away() | round_ties_away() |
round_toward_positive() | round_ceiling() |
round_toward_negative() | round_floor() |
round_toward_zero() | round_trunc() |
Note that IEEE 754 has no name for the other three tie-breaking procedures
in round_ties_up() and friends, nor for rounding away from zero
(round_anti_trunc()), nor for the custom thresholds of
round_up_from().
References
IEEE (2019). IEEE Standard for Floating-Point Arithmetic. https://doi.org/10.1109/IEEESTD.2019.8766229
See also
round_ties_up() and friends for the same tie-breaking
procedures under names that do not presuppose the standard, and
reround() for reaching any of them through a rounding string.
Examples
# Round to the nearest value. In case of a tie,
# the result is hard to predict but tends to be even:
round_ties_to_even(1.25, digits = 1)
#> [1] 1.2
round_ties_to_even(-1.25, digits = 1)
#> [1] -1.2
# Round to the nearest value. In case of a tie,
# round away from zero:
round_ties_to_away(1.25, digits = 1)
#> [1] 1.3
round_ties_to_away(-1.25, digits = 1)
#> [1] -1.3
# Always round to the greater value:
round_toward_positive(0.721, digits = 2)
#> [1] 0.73
round_toward_positive(-0.721, digits = 2)
#> [1] -0.72
# Always round to the lesser value:
round_toward_negative(3.249, digits = 2)
#> [1] 3.24
round_toward_negative(-3.249, digits = 2)
#> [1] -3.25
# Always round toward zero:
round_toward_zero(6.38, digits = 1)
#> [1] 6.3
round_toward_zero(-6.38, digits = 1)
#> [1] -6.3