feat: add decimal argument support to round function

The round function has a number of variants to support different numeric types.  This commit adds support for rounding decimals.

The precision of the resultant decimal type is one greater than
the precision of the input decimal to allow for rounding up to the
next decimal digit.
The scale of the resultant decimal type is the same as the input type since the result of rounding cannot add any further decimal places.

Signed-off-by: Andrew Coleman <[email protected]>

Author: andrew-coleman

extensions/functions_rounding_decimal.yaml

@@ -0,0 +1,82 @@
+%YAML 1.2
+---
+scalar_functions:
+  -
+    name: "ceil"
+    description: >
+      Rounding to the ceiling of the value `x`.
+    impls:
+      - args:
+          - value: decimal<P,S>
+            name: x
+        return: |-
+          integral_least_num_digits = P - S + 1
+          precision = min(integral_least_num_digits, 38)
+          decimal?<precision, 0>
+  -
+    name: "floor"
+    description: >
+      Rounding to the floor of the value `x`.
+    impls:
+      - args:
+          - value: decimal<P,S>
+            name: x
+        return: |-
+          integral_least_num_digits = P - S + 1
+          precision = min(integral_least_num_digits, 38)
+          decimal?<precision, 0>
+  -
+    name: "round"
+    description: >
+      Rounding the value `x` to `s` decimal places.
+    impls:
+      - args:
+          - value: decimal<P,S>
+            name: x
+            description: >
+              Numerical expression to be rounded.
+          - value: i32
+            name: s
+            description: >
+              Number of decimal places to be rounded to.
+
+              When `s` is a positive number, the rounding
+              is performed to a `s` number of decimal places.
+
+              When `s` is a negative number, the rounding is
+              performed to the left side of the decimal point
+              as specified by `s`.
+
+              The precision of the resultant decimal type is one
+              more than the precision of the input decimal type to
+              allow for numbers that round up or down to the next
+              decimal magnitude.
+              E.g. `round(9.9, 0)` -> `10.0`.
+              The scale of the resultant decimal type cannot be
+              larger than the scale of the input decimal type.
+        options:
+          rounding:
+            description: >
+              When a boundary is computed to lie somewhere between two values,
+              and this value cannot be exactly represented, this specifies how
+              to round it.
+
+                - TIE_TO_EVEN: round to nearest value; if exactly halfway, tie
+                  to the even option.
+                - TIE_AWAY_FROM_ZERO: round to nearest value; if exactly
+                  halfway, tie away from zero.
+                - TRUNCATE: always round toward zero.
+                - CEILING: always round toward positive infinity.
+                - FLOOR: always round toward negative infinity.
+                - AWAY_FROM_ZERO: round negative values with FLOOR rule, round positive values with CEILING rule
+                - TIE_DOWN: round ties with FLOOR rule
+                - TIE_UP: round ties with CEILING rule
+                - TIE_TOWARDS_ZERO: round ties with TRUNCATE rule
+                - TIE_TO_ODD: round to nearest value; if exactly halfway, tie
+                  to the odd option.
+            values: [ TIE_TO_EVEN, TIE_AWAY_FROM_ZERO, TRUNCATE, CEILING, FLOOR,
+              AWAY_FROM_ZERO, TIE_DOWN, TIE_UP, TIE_TOWARDS_ZERO, TIE_TO_ODD ]
+        nullability: DECLARED_OUTPUT
+        return: |-
+          precision = min(P + 1, 38)
+          decimal?<precision, S>

tests/cases/rounding_decimal/ceil.test

@@ -0,0 +1,7 @@
+### SUBSTRAIT_SCALAR_TEST: v1.0
+### SUBSTRAIT_INCLUDE: '/extensions/functions_rounding_decimal.yaml'
+
+# basic: Basic examples without any special cases
+ceil(2.25::dec<3,2>) = 3::dec<2,0>
+ceil(-65.5::dec<3,1>) = -65::dec<3,0>
+ceil(9.9::dec<2,1>) = 10::dec<2,0>

tests/cases/rounding_decimal/floor.test

@@ -0,0 +1,6 @@
+### SUBSTRAIT_SCALAR_TEST: v1.0
+### SUBSTRAIT_INCLUDE: '/extensions/functions_rounding_decimal.yaml'
+
+# basic: Basic examples without any special cases
+floor(2.25::dec<3,2>) = 2::dec<2,0>
+floor(-65.5::dec<3,1>) = -66::dec<3,0>

tests/cases/rounding_decimal/round.test

@@ -0,0 +1,11 @@
+### SUBSTRAIT_SCALAR_TEST: v1.0
+### SUBSTRAIT_INCLUDE: '/extensions/functions_rounding_decimal.yaml'
+
+# basic: Basic examples without any special cases
+round(2.0::dec<2,1>, 2::i32) = 2::dec<3,1>
+round(2.75::dec<3,2>, 1::i32) = 2.8::dec<4,2>
+
+# negative_rounding: Examples with negative rounding
+round(2.0::dec<2,1>, -2::i32) = 0::dec<3,1>
+round(123::dec<3,0>, -2::i32) = 100::dec<4,0>
+round(8793.5::dec<5,1>, -2::i32) = 8800::dec<6,1>