feat: add mode option to round (#375)

Context: pola-rs/polars#21800

Adds optional round mode option to series and expr, defaults to `halftoeven`

Author: b-twice

__tests__/expr.test.ts

@@ -791,6 +791,22 @@ describe("expr", () => {
     const actual = df.select(col("a").round({ decimals: 2 }).as("rounded"));
     expect(actual).toFrameStrictEqual(expected);
   });
+  test("round:halfawayfromzero:opt", () => {
+    const df = pl.DataFrame({ a: [1.00523, 2.35878, 3.3349999] });
+    const expected = pl.DataFrame({ rounded: [1.01, 2.36, 3.33] });
+    const actual = df.select(
+      col("a").round({ decimals: 2, mode: "halfawayfromzero" }).as("rounded"),
+    );
+    expect(actual).toFrameStrictEqual(expected);
+  });
+  test("round:halfawayfromzero", () => {
+    const df = pl.DataFrame({ a: [1.00523, 2.35878, 3.3349999] });
+    const expected = pl.DataFrame({ rounded: [1.01, 2.36, 3.33] });
+    const actual = df.select(
+      col("a").round(2, "halfawayfromzero").as("rounded"),
+    );
+    expect(actual).toFrameStrictEqual(expected);
+  });
   test("sample", () => {
     const df = pl.DataFrame({ n: [1, 2, 3] });
     let actual = df.withColumns(

__tests__/series.test.ts

@@ -720,6 +720,18 @@ describe("series functions", () => {
     const actual = s.round(2);
     expect(actual).toSeriesEqual(expected);
   });
+  test("round:halfawayfromzero", () => {
+    const s = pl.Series([1.5, 2.5, -1.5, -2.5]);
+    const expected = pl.Series([2, 3, -2, -3]);
+    const actual = s.round(0, "halfawayfromzero");
+    expect(actual).toSeriesEqual(expected);
+  });
+  test("round:halfawayfromzero:opt", () => {
+    const s = pl.Series([1.5, 2.5, -1.5, -2.5]);
+    const expected = pl.Series([2, 3, -2, -3]);
+    const actual = s.round({ decimals: 0, mode: "halfawayfromzero" });
+    expect(actual).toSeriesEqual(expected);
+  });
   test("round:named", () => {
     const s = pl.Series([1.1111, 2.2222]);
     const expected = pl.Series([1.11, 2.22]);

polars/lazy/expr/index.ts

@@ -27,6 +27,7 @@ import type {
   FillNullStrategy,
   InterpolationMethod,
   RankMethod,
+  RoundMode,
 } from "../../types";
 import {
   type ExprOrString,
@@ -1777,8 +1778,13 @@ export const _Expr = (_expr: any): Expr => {
 
       return wrap("rollingSkew", val.windowSize, val.bias ?? bias);
     },
-    round(decimals) {
-      return _Expr(_expr.round(decimals?.decimals ?? decimals, "halftoeven"));
+    round(decimals, mode?: RoundMode) {
+      return _Expr(
+        _expr.round(
+          decimals?.decimals ?? decimals,
+          decimals?.mode ?? mode ?? "halftoeven",
+        ),
+      );
     },
     sample(opts?, frac?, withReplacement = false, seed?) {
       if (opts?.n !== undefined || opts?.frac !== undefined) {

polars/series/index.ts

@@ -1693,15 +1693,14 @@ export function _Series(_s: any): Series {
     ceil() {
       return wrap("ceil");
     },
-    round(opt): any {
-      const mode = "halftoeven";
-      if (this.isNumeric()) {
-        if (typeof opt === "number") {
-          return wrap("round", opt, mode);
-        }
-        return wrap("round", opt.decimals, mode);
+    round(opt, mode): any {
+      if (!this.isNumeric()) {
+        throw new InvalidOperationError("round", this.dtype);
+      }
+      if (typeof opt === "number") {
+        return wrap("round", opt, mode ?? "halftoeven");
       }
-      throw new InvalidOperationError("round", this.dtype);
+      return wrap("round", opt.decimals, opt.mode ?? "halftoeven");
     },
     clip(...args) {
       return expr_op("clip", ...args);

polars/shared_traits.ts

@@ -6,6 +6,7 @@ import type {
   RollingOptions,
   RollingQuantileOptions,
   RollingSkewOptions,
+  RoundMode,
 } from "./types";
 import type { ColumnsOrExpr, StartBy } from "./utils";
 
@@ -426,10 +427,16 @@ export interface Round<T> {
    *
    * Similar functionality to javascript `toFixed`
    * @param decimals number of decimals to round by.
+   * @param mode Rounding mode, the default is "half to even" (also known as "bankers' rounding").
+            RoundMode.
+            * *halftoeven*
+                round to the nearest even number
+            * *halfawayfromzero*
+                round to the nearest number away from zero
    * @category Math
    */
-  round(decimals: number): T;
-  round(options: { decimals: number }): T;
+  round(decimals: number, mode?: RoundMode): T;
+  round(options: { decimals: number; mode?: RoundMode }): T;
   /**
    * Floor underlying floating point array to the lowest integers smaller or equal to the float value.
    * Only works on floating point Series

polars/types.ts

@@ -35,6 +35,11 @@ export type RankMethod =
   | "ordinal"
   | "random";
 
+/**
+ * Round modes
+ */
+export type RoundMode = "halftoeven" | "halfawayfromzero";
+
 /**
  * Options for {@link concat}
  */