[New Feature] Support decimal:quantize langlib function

[chiranSachintha]

# IEEE quantize operation.
# + x - decimal value to operate on
# + y - decimal value from which to get the quantum
# + return - `x` with the quantum of `y`
public isolated function quantize(decimal x, decimal y) returns decimal = external;

For this, we use the IEEE semantics of the quantize function.

quantize(source, source)
For finite decimal operands x and y of the same format, quantize(x, y) is a floating-point number in the same 
format that has, if possible, the same numerical value as x and the same quantum as y. 
If the exponent is being increased, rounding according to the applicable rounding direction the attribute 
might occur: the result is a different floating-point representation and the inexact exception is signaled if the 
result does not have the same numerical value as x. If the exponent is being decreased and the significant 
of the result would have more than p digits, the invalid operation exception is signaled and the result is NaN. 
Otherwise, if only one operand is infinite then the invalid operation exception is signaled and the result is NaN. 
If both operands are infinite then the result is canonical ∞ with the sign of x. 
quantize does not signal underflow or overflow.

* here p digits means the maximum number of digits that can be included in 128-bit decimal (radix 10) floating-point number.

For more details, you can follow the 5.3.2 section of IEEE spec.

In this discussion,
The exponent of LHS means the exponent of the first argument of the quantize function
The exponent of RHS means the exponent of the second argument of the quantize function

Examples

Example 1

quantize(3.26, 0.001) ==> 3.260
Explanation: if the exponent of LHS is being decreased related to the exponent of RHS, the result will multiply by the positive power of 10. Here exponent decrease from -2 to -3.

Example 2

quantize(3.26, 0.01) ==> 3.26
Explanation: if the exponent of LHS is already equal to the exponent of RHS, the result is unchanged. Here the exponent of both LHS and RHS is equal to -2.

Example 3

quantize(3.26, 0.1) ==> 3.3
Explanation: if the exponent of LHS  is being increased related to the exponent of RHS, the result will round according to the applicable rounding direction. Here exponent increase from -2 to -1. 

following cases are not valid with ballerina spec. because we do not support NaN

Example 4

quantize(NaN, NaN) ==> NaN
quantize(-NaN, NaN) ==> -NaN
Explanation: if both are infinite then the result is the first operand.

Example 5

quantize(2, NaN) ==> NaN, invalid operation exception is signaled
quantize(NaN, 2) ==> NaN, invalid operation exception is signaled
quantize(-NaN, 2) ==> -NaN, invalid operation exception is signaled

Implementation design
p means the maximum number of digits in the significand of 128-bit decimal (radix 10) floating-point number(equals 34).

• https://docs.oracle.com/javase/7/docs/api/java/math/RoundingMode.html
• https://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html#setScale-int-

Highly appreciate your input on this discussion.

[chiranSachintha]

@gimantha @KavinduZoysa @hasithaa @MaryamZi @suleka96

[gimantha]

Example 4
quantize(NaN, NaN) ==> NaN
quantize(-NaN, NaN) ==> -NaN
Explanation: if both are infinite then the result is the first operand.

Example 5
quantize(2, NaN) ==> NaN, invalid operation exception is signaled
quantize(NaN, 2) ==> NaN, invalid operation exception is signaled
quantize(-NaN, 2) ==> -NaN, invalid operation exception is signaled

quantize is for decimal only. Why do we need to support NaN? Probably code will give a compile error. Or am I missing something else?

[chiranSachintha]

These scenarios are not valid as I mentioned above. I have mentioned those scenarios for the sake of completion.

following cases are not valid with ballerina spec. because we do not support NaN

[KavinduZoysa]

@chiranSachintha, the overall design looks okay to me. (Your flow chart will be more clear if you use something like exp_diff instead of exp)
Can you provide an example that gives val == inf(as mentioned in flow chart)?
Also can you explain what is the method you are going to use to get the exponent of decimal value.

[chiranSachintha]

In java, any BigDecimal value represents by unscaledValue × 10^-scale. So we can use scale() function to get exponent. Refer to https://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html

[KavinduZoysa]

So if the value is 1.2345e2, scale() returns 6, is that correct?

[chiranSachintha]

scale of 1.2345e2 is 2. (12345 x 10^-2)

[SandaruJayawardana]

I think, we can add another optional parameter to get the rounding direction @chiranSachintha
According to the IEEE standard, we can support that functionality.

If the exponent is being increased, rounding according to the applicable rounding direction the attribute 
might occur

Python also supports both up and down rounding directions. Refer to quantize(exp, rounding=None, context=None)

[SandaruJayawardana]

Raised this in spec repo ballerina-platform/ballerina-spec#322 (comment)