Skip to main content

Column.round

rounddecimal_placesuse_bankers

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.