code review for numeric functions
diff --git a/asterix-doc/src/site/markdown/aql/functions.md b/asterix-doc/src/site/markdown/aql/functions.md
index af1e2e4..7b2fb03 100644
--- a/asterix-doc/src/site/markdown/aql/functions.md
+++ b/asterix-doc/src/site/markdown/aql/functions.md
@@ -1,5 +1,5 @@
# Asterix: Using Functions #
-Asterix provides various classes of functions to support operations on string, spatial, and temporal data. This document explains how to use these functions.
+Asterix provides various classes of functions to support operations on numeric, string, spatial, and temporal data. This document explains how to use these functions.
## Numeric Functions ##
### numeric-abs ###
@@ -7,11 +7,11 @@
numeric-abs(numeric_expression)
- * Returns the absolute value of the argument.
+ * Computes the absolute value of the argument.
* Arguments:
* `numeric_expression`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
* Return Value:
- * The absolute value of the argument.
+ * The absolute value of the argument with the same type as the input argument, or `null` if the argument is a `null` value.
* Example:
@@ -33,11 +33,11 @@
numeric-ceiling(numeric_expression)
- * Returns the smallest value that is greater than or equal to the argument and is equal to an integer value. If the argument value is already equal to mathematical integer, then the result is the same as the argument.
+ * Computes the smallest (closest to negative infinity) number with no fractional part that is not less than the value of the argument. If the argument is already equal to mathematical integer, then the result is the same as the argument.
* Arguments:
* `numeric_expression`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
* Return Value:
- * The smallest value that is greater than or equal to the argument and is equal to a mathematical integer value.
+ * The ceiling value for the given number in the same type as the input argument, or `null` if the input is `null`.
* Example:
@@ -59,11 +59,11 @@
numeric-floor(numeric_expression)
- * Returns the largest value that is less than or equal to the argument and is equal to an integer value. If the argument is already equal to mathematical integer, then the result is the same as the argument.
+ * Computes the largest (closest to positive infinity) number with no fractional part that is not greater than the value. If the argument is already equal to mathematical integer, then the result is the same as the argument.
* Arguments:
* `numeric_expression`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
* Return Value:
- * The largest value that is less than or equal to the argument and is equal to a mathematical integer value.
+ * The floor value for the given number in the same type as the input argument, or `null` if the input is `null`.
* Example:
@@ -85,11 +85,11 @@
numeric-round(numeric_expression)
- * Returns the closest integer value to the argument.
+ * Computes the number with no fractional part that is closest (and also closest to positive infinity) to the argument.
* Arguments:
* `numeric_expression`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
* Return Value:
- * The value of the argument rounded to the nearest integer value.
+ * The rounded value for the given number in the same type as the input argument, or `null` if the input is `null`.
* Example:
@@ -109,27 +109,31 @@
### numeric-round-half-to-even ###
* Syntax:
- numeric-round-half-to-even(numeric_expression)
+ numeric-round-half-to-even(numeric_expression, [precision])
- * Returns the value rounded towards the "nearest integer neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. Note that this is the rounding mode that minimizes cumulative error when applied repeatedly over a sequence of calculations.
+ * Computes the closest numeric value to `numeric_expression` that is a multiple of ten to the power of minus `precision`. `precision` is optional and by default value `0` is used.
* Arguments:
- * `numeric_expression`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
+ * `numeric_expression`: A `int8`/`int16`/`int32`/`int64`/`float`/`double` value.
+ * `precision`: An optional integer field representing the number of digits in the fraction of the the result
* Return Value:
- * The value rounded towards the "nearest integer neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
+ * The rounded value for the given number in the same type as the input argument, or `null` if the input is `null`.
* Example:
- let $v1 := numeric-round-half-to-even(-2.5)
- let $v2 := numeric-round-half-to-even(-1.5)
- let $v3 := numeric-round-half-to-even(0.5)
- let $v4 := numeric-round-half-to-even(1.5)
- let $v5 := numeric-round-half-to-even(2.5)
- return { "v1": $v1, "v2": $v2, "v3": $v3, "v4": $v4, "v5": $v5 }
+ let $v1 := numeric-round-half-to-even(2013)
+ let $v2 := numeric-round-half-to-even(-4036)
+ let $v3 := numeric-round-half-to-even(0.8)
+ let $v4 := numeric-round-half-to-even(float("-2013.256"))
+ let $v5 := numeric-round-half-to-even(double("-2013.893823748327284"))
+ let $v6 := numeric-round-half-to-even(double("-2013.893823748327284"), 2)
+ let $v7 := numeric-round-half-to-even(2013, 4)
+ let $v8 := numeric-round-half-to-even(float("-2013.256"), 5)
+ return { "v1": $v1, "v2": $v2, "v3": $v3, "v4": $v4, "v5": $v5, "v6": $v6, "v7": $v7, "v8": $v8 }
* The expected result is:
- { "v1": -2.0d, "v2": -2.0d, "v3": 0.0d, "v4": 2.0d, "v5": 2.0d }
+ { "v1": 2013, "v2": -4036, "v3": 1.0d, "v4": -2013.0f, "v5": -2014.0d, "v6": -2013.89d, "v7": 2013, "v8": -2013.256f }
## String Functions ##