Column.round
Group: Math
Documentation
Round the values in a numeric column to a specified number of decimal places. For integers, rounding to 0 or more decimal places simply returns the argument. For negative decimal places, see below. By default, rounding uses "asymmetric round-half-up", also known as "round towards positive infinity." If use_bankers=True, then it uses "round-half-even", also known as "banker's rounding". If the column is of type Float
and decimal_places
> 0, round
returns a column of Float
; otherwise, it returns a column of Integer
.
Arguments
decimal_places
: The number of decimal places to round to. Can be negative, which results in rounding to positive integer powers of 10. Must be between -15 and 15 (inclusive).use_bankers
: Rounds mid-point to nearest even number.on_problems
: Specifies how to handle if a problem occurs, raising as a warning by default.
Examples
Round a column of Float
values`.
Column.from_vector "foo" [1.2, 2.3, 3.6] . round == (Column.from_vector "foo" [1, 2, 4])
Errors
Reports Illegal_Argument
if the number is 15 or more decimal places.
Above 14 digits, it is possible that the underlying long, converted to
double in the rounding process, would lose precision in the least
significant bits.
(See https://en.wikipedia.org/wiki/Double-precision_floating-point_format.)
If decimal_places
is outside the range -15..15 (inclusive), an
Illegal_Argument
error is thrown.
Remarks
Precision
As floating-point numbers are inexact, rounding can have unexpected results near the precision limit (about 15 decimal places), especially when rounding mid-point values. For example:
Rounding 1.2222222222222235 to 15 decimal places returns:
- 1.222222222222224 in Postgres.
- 1.222222222222223 in SQLite.
Negative decimal place counts
Rounding to n
digits can be thought of as "rounding to the nearest
multiple of 10^(-n)". For negative decimal counts, this results in
rounding to the nearest positive integer power of 10.