EpsilonPrime commented on code in PR #36289:
URL: https://github.com/apache/arrow/pull/36289#discussion_r1248330964
##########
docs/source/cpp/compute.rst:
##########
@@ -563,30 +563,34 @@ representation based on the rounding criterion.
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| floor | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundOptions` | (1)(2) |
+| round | Unary | Numeric | Input Type |
:struct:`RoundOptions` | (1)(2) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round_to_multiple | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundToMultipleOptions` | (1)(3) |
+| round_to_multiple | Unary | Numeric | Input Type |
:struct:`RoundToMultipleOptions` | (1)(3) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| trunc | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-* \(1) Output value is a 64-bit floating-point for integral inputs and the
- retains the same type for floating-point and decimal inputs. By default
- rounding functions displace a value to the nearest integer using
- HALF_TO_EVEN to resolve ties. Options are available to control the rounding
- criterion. Both ``round`` and ``round_to_multiple`` have the ``round_mode``
- option to set the rounding mode.
+* \(1) By default rounding functions displace a value to the nearest
+ integer using HALF_TO_EVEN to resolve ties. Options are available to
control
+ the rounding criterion. Both ``round`` and ``round_to_multiple`` have the
+ ``round_mode`` option to set the rounding mode.
* \(2) Round to a number of digits where the ``ndigits`` option of
:struct:`RoundOptions` specifies the rounding precision in terms of number
of digits. A negative value corresponds to digits in the non-fractional
part. For example, -2 corresponds to rounding to the nearest multiple of
100 (zeroing the ones and tens digits). Default value of ``ndigits`` is 0
- which rounds to the nearest integer.
+ which rounds to the nearest integer. For integer inputs a non-negative
+ ``ndigits`` value is ignored and the input is returned unchanged. For integer
+ inputs, if ``-ndigits`` is larger than the maximum number of digits the
+ input type can hold, it is truncated to the maximum digit. For example,
+ ``round([123], ndigits=-4, round_mode=DOWN)`` returns [100] for ``int8``
type.
Review Comment:
There are three potential ways of handling this particular behavior (none of
which are specified in the Substrait specification):
- reject the operation as invalid
- using the provided value (always returning overflow)
- using the provided value (always returning max value)
- fixing the value and proceeding
I am going to check other engines to see what they do in this particular
case but the precedent within arrow seems to be to reject the operation as an
overflow would occur (RoundToMultiple does this).
##########
docs/source/cpp/compute.rst:
##########
@@ -563,30 +563,34 @@ representation based on the rounding criterion.
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| floor | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundOptions` | (1)(2) |
+| round | Unary | Numeric | Input Type |
:struct:`RoundOptions` | (1)(2) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round_to_multiple | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundToMultipleOptions` | (1)(3) |
+| round_to_multiple | Unary | Numeric | Input Type |
:struct:`RoundToMultipleOptions` | (1)(3) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| trunc | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-* \(1) Output value is a 64-bit floating-point for integral inputs and the
- retains the same type for floating-point and decimal inputs. By default
- rounding functions displace a value to the nearest integer using
- HALF_TO_EVEN to resolve ties. Options are available to control the rounding
- criterion. Both ``round`` and ``round_to_multiple`` have the ``round_mode``
- option to set the rounding mode.
+* \(1) By default rounding functions displace a value to the nearest
+ integer using HALF_TO_EVEN to resolve ties. Options are available to
control
+ the rounding criterion. Both ``round`` and ``round_to_multiple`` have the
+ ``round_mode`` option to set the rounding mode.
* \(2) Round to a number of digits where the ``ndigits`` option of
:struct:`RoundOptions` specifies the rounding precision in terms of number
of digits. A negative value corresponds to digits in the non-fractional
part. For example, -2 corresponds to rounding to the nearest multiple of
100 (zeroing the ones and tens digits). Default value of ``ndigits`` is 0
- which rounds to the nearest integer.
+ which rounds to the nearest integer. For integer inputs a non-negative
+ ``ndigits`` value is ignored and the input is returned unchanged. For integer
+ inputs, if ``-ndigits`` is larger than the maximum number of digits the
+ input type can hold, it is truncated to the maximum digit. For example,
Review Comment:
maximum ndigits that the type can handle
##########
docs/source/cpp/compute.rst:
##########
@@ -563,30 +563,34 @@ representation based on the rounding criterion.
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| floor | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundOptions` | (1)(2) |
+| round | Unary | Numeric | Input Type |
:struct:`RoundOptions` | (1)(2) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round_to_multiple | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundToMultipleOptions` | (1)(3) |
+| round_to_multiple | Unary | Numeric | Input Type |
:struct:`RoundToMultipleOptions` | (1)(3) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| trunc | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-* \(1) Output value is a 64-bit floating-point for integral inputs and the
- retains the same type for floating-point and decimal inputs. By default
- rounding functions displace a value to the nearest integer using
- HALF_TO_EVEN to resolve ties. Options are available to control the rounding
- criterion. Both ``round`` and ``round_to_multiple`` have the ``round_mode``
- option to set the rounding mode.
+* \(1) By default rounding functions displace a value to the nearest
+ integer using HALF_TO_EVEN to resolve ties. Options are available to
control
+ the rounding criterion. Both ``round`` and ``round_to_multiple`` have the
+ ``round_mode`` option to set the rounding mode.
* \(2) Round to a number of digits where the ``ndigits`` option of
:struct:`RoundOptions` specifies the rounding precision in terms of number
of digits. A negative value corresponds to digits in the non-fractional
part. For example, -2 corresponds to rounding to the nearest multiple of
100 (zeroing the ones and tens digits). Default value of ``ndigits`` is 0
- which rounds to the nearest integer.
+ which rounds to the nearest integer. For integer inputs a non-negative
+ ``ndigits`` value is ignored and the input is returned unchanged. For integer
+ inputs, if ``-ndigits`` is larger than the maximum number of digits the
+ input type can hold, it is truncated to the maximum digit. For example,
+ ``round([123], ndigits=-4, round_mode=DOWN)`` returns [100] for ``int8``
type.
Review Comment:
(as the ndigits value is silently reduced to -2)
##########
docs/source/cpp/compute.rst:
##########
@@ -563,30 +563,34 @@ representation based on the rounding criterion.
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| floor | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundOptions` | (1)(2) |
+| round | Unary | Numeric | Input Type |
:struct:`RoundOptions` | (1)(2) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-| round_to_multiple | Unary | Numeric | Float32/Float64/Decimal |
:struct:`RoundToMultipleOptions` | (1)(3) |
+| round_to_multiple | Unary | Numeric | Input Type |
:struct:`RoundToMultipleOptions` | (1)(3) |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
| trunc | Unary | Numeric | Float32/Float64/Decimal |
| |
+-------------------+------------+-------------+-------------------------+----------------------------------+--------+
-* \(1) Output value is a 64-bit floating-point for integral inputs and the
- retains the same type for floating-point and decimal inputs. By default
- rounding functions displace a value to the nearest integer using
- HALF_TO_EVEN to resolve ties. Options are available to control the rounding
- criterion. Both ``round`` and ``round_to_multiple`` have the ``round_mode``
- option to set the rounding mode.
+* \(1) By default rounding functions displace a value to the nearest
+ integer using HALF_TO_EVEN to resolve ties. Options are available to
control
+ the rounding criterion. Both ``round`` and ``round_to_multiple`` have the
+ ``round_mode`` option to set the rounding mode.
* \(2) Round to a number of digits where the ``ndigits`` option of
:struct:`RoundOptions` specifies the rounding precision in terms of number
of digits. A negative value corresponds to digits in the non-fractional
part. For example, -2 corresponds to rounding to the nearest multiple of
100 (zeroing the ones and tens digits). Default value of ``ndigits`` is 0
- which rounds to the nearest integer.
+ which rounds to the nearest integer. For integer inputs a non-negative
+ ``ndigits`` value is ignored and the input is returned unchanged. For integer
+ inputs, if ``-ndigits`` is larger than the maximum number of digits the
+ input type can hold, it is truncated to the maximum digit. For example,
+ ``round([123], ndigits=-4, round_mode=DOWN)`` returns [100] for ``int8``
type.
+ For integer inputs, an error is returned on overflow.
* \(3) Round to a multiple where the ``multiple`` option of
:struct:`RoundToMultipleOptions` specifies the rounding scale. The rounding
- multiple has to be a positive value. For example, 100 corresponds to
- rounding to the nearest multiple of 100 (zeroing the ones and tens digits).
- Default value of ``multiple`` is 1 which rounds to the nearest integer.
+ multiple has to be a positive value and can be casted to input type.
+ For example, 100 corresponds to ounding to the nearest multiple of 100
Review Comment:
ounding -> rounding
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
