Java: Add support for additional rounding rules in arithmetic operations and other functions

[A1trdX]

Currently, the arithmetic operations (e.g. multiply(), divide(), etc.) and other functions in Decimal64Utils (from dfp) and Decimal64MathUtils (from dfp-math) apparently support only one rounding rule: "Round to nearest, ties to even."

However, IEEE-754 standard also defines:

• Rounding to nearest, ties away from zero
• Round toward positive infinity
• Round toward negative infinity
• Round toward zero (truncation)

The last three are implemented on Intel hardware.

Could you add support for the remaining rounding rules of the IEEE-754 standard? Or at least for the last three?

This is how I see it in the API. For each method that requires rounding, add a similar one with the ability to specify a rounding rule, for example: long divide(long x, long y, RoundingMode mode).

[agdavydov81]

@A1trdX First of all, thank you for your interest in the library.

Yes, I am aware of the different rounding modes in IEEE-754 and Intel's implementation.
However, in our experience, we have never needed alternative types of rounding for mathematical operations.

So, do you actually need different rounding modes for mathematical operations, or are you simply aiming to provide greater flexibility in your code?
I cannot imagine a real-world scenario where a different rounding mode for mathematical calculations is necessary.

Typically, rounding implies that you also need to specify the number of decimal places to use when rounding a number. However, this is not the case for mathematical operations. Therefore, specifying a different rounding mode for mathematical operations will not speed up your code.

Could you please provide a real-world example where this would be required?

[A1trdX]

Mostly, it's probably a matter of flexibility and control. But also, to reduce the headache and avoid having to think about how to handle rounding situations, I personally prefer to use the "towards zero" (truncate) rounding rule, especially when dividing. This allows me to avoid having to think too much about how to handle numbers later. But there are some situations in which I think it would be better to have a specific rounding rule for the operation at hand.

For example, let's take trading. We need to open a simple position and two exit orders – SL (Stop-Loss) and TP (Take-Profit). In the settings, the user specifies the % distance for each. According to the conditions, prices must meet the following rules:

• The distance to the SL cannot exceed the specified percentage (an excessively large SL may exceed the liquidation price)
• The distance to the TP cannot be less than the specified percentage (at least the specified percentage of profit must be guaranteed)

To determine the price, we multiply the entry price by the distance percentage (I personally divide all percentages by 100 beforehand for convenience and to avoid repeating this for each subsequent operation). Example of determining the SL price:

slPrice = entryPrice * (1 - slPercent) // Long
slPrice = entryPrice * (1 + slPercent) // Short

When we have the option to choose the rounding rule, we can implement this very easily. For SL, we set the rule "towards zero." For TP, depending on the position direction (Long or Short), we choose "towards positive infinity" or "towards negative infinity."

If we don't have this option, and the default multiplication operation has a rounding rule of "to nearest, ties to even," then we'll encounter a situation where, after rounding, the price violates one of the rules we initially set. We'll have to perform additional checks and operations to resolve this issue. This, in turn:

• Impacts performance (not significantly in the case of orders, but it does have an impact)
• Code complexity
• Implementation time

Let's look at a concrete example using numbers.

entryPrice = 12345678.12345678
minTick = 0.00000001
slPercent = 0.01 // 1%

Then for a Short position:

slPrice = entryPrice * (1 + slPercent)
slPrice = 12345678.12345678 * (1 + 0.01)
slPrice = 12469134.9046913478 // Exact number, not rounded to 16 significant digits
slPrice = 12469134.90469135   // Rule violated, must be 12469134.90469134

This may not be the most ideal example, but I think in theory there are other similar situations where not only similar rules need to be taken into account but also numerous calculations need to be performed. All this in theory affects not only the operations of multiplication and division, but can also affect, for example, trigonometric functions. I wouldn't want to have to convert DFP to BigDecimal every time, perform operations in a 64-bit context, and then convert back to DFP.

[A1trdX]

@agdavydov81 I found another situation that requires specific rounding mode in the divide operation, otherwise a problem occurs.

I'm implementing my own helper for operations with Decimal64 numbers and have added the following two methods, which are missing in Decimal64Utils and Decimal64MathUtils:

public @Decimal long remainder(@Decimal long a, @Decimal long b) {
    @Decimal long truncatedQuotient = Decimal64MathUtils.roundIntegralZero(Decimal64Utils.divide(a, b));
    return Decimal64Utils.subtract(a, Decimal64Utils.multiply(b, truncatedQuotient));
}

public @Decimal long[] divideAndRemainder(@Decimal long a, @Decimal long b) {
    @Decimal long truncatedQuotient  = Decimal64MathUtils.roundIntegralZero(Decimal64Utils.divide(a, b));
    @Decimal long remainder = Decimal64Utils.subtract(a, Decimal64Utils.multiply(b, truncatedQuotient));
    return new long[] { truncatedQuotient, remainder };
}

In some cases, Decimal64Utils.divide(a, b) rounds a number up to an integer. As a result, the remainder is calculated incorrectly.

Let's look at an example using the remainder(...) method:

a = 2000000000000003 // 16 digits
b = 2

Decimal64Utils.divide(a, b) = 2000000000000003 / 2 
Decimal64Utils.divide(a, b) = 1000000000000001.5    // More than 16 digits, round to nearest, ties to even.
Decimal64Utils.divide(a, b) = 1000000000000002      // Error. Must be 1000000000000001, rounding towards zero is required in the previous step.

truncatedQuotient = Decimal64MathUtils.roundIntegralZero(1000000000000002)
truncatedQuotient = 1000000000000002

remainder = Decimal64Utils.subtract(2000000000000003, Decimal64Utils.multiply(2, 1000000000000002))
remainder = Decimal64Utils.subtract(2000000000000003, 2000000000000004)
remainder = -1  // Error. Must be 1.

If we could specify the rounding mode "towards zero" when dividing, this problem would not arise:

a = 2000000000000003
b = 2

Decimal64Utils.divide(a, b) = 2000000000000003 / 2 
Decimal64Utils.divide(a, b) = 1000000000000001.5    // More than 16 digits, round towards zero
Decimal64Utils.divide(a, b) = 1000000000000001

truncatedQuotient = Decimal64MathUtils.roundIntegralZero(1000000000000001)
truncatedQuotient = 1000000000000001

remainder = Decimal64Utils.subtract(2000000000000003, Decimal64Utils.multiply(2, 1000000000000001))
remainder = Decimal64Utils.subtract(2000000000000003, 1000000000000002)
remainder = 1   // Correct

[A1trdX]

Another situation. Decimal64Utils has the following methods that allow rounding to multiple:

• Decimal64Utils.roundToNearestTiesAwayFromZero(long value, long multiple)
• Decimal64Utils.roundToNearestTiesToEven(long value, long multiple)
• Decimal64Utils.roundTowardsNegativeInfinity(long value, long multiple)
• Decimal64Utils.roundTowardsPositiveInfinity(long value, long multiple)

But for some reason, Decimal64Utils.roundTowardsZero(long value, long multiple) is missing.

So I added a universal method to my helper that should work with all rounding modes:

public @Decimal long roundToMultiple(@Decimal long value, @Decimal long multiple, RoundingMode roundingMode) {
    requireFiniteNumberArgument(value, "value");
    requireFiniteNumberArgument(multiple, "multiple");

    if (Decimal64Utils.compareTo(multiple, Decimal64Utils.ZERO) <= 0) {
        reportIllegalArgument("multiple", "> 0");
    }

    @Decimal long ratio = divide(value, multiple);
    @Decimal long ratioRounded = switch (roundingMode) {
        case CEILING -> Decimal64Utils.roundTowardsPositiveInfinity(ratio);
        case FLOOR -> Decimal64Utils.roundTowardsNegativeInfinity(ratio);
        case HALF_UP -> Decimal64Utils.roundToNearestTiesAwayFromZero(ratio);
        case HALF_EVEN -> Decimal64Utils.roundToNearestTiesToEven(ratio);
        case DOWN -> Decimal64Utils.roundTowardsZero(ratio);
        default -> throw new RuntimeException("Unsupported rounding mode: " + roundingMode);
    };
    return multiply(ratioRounded, multiple);
}

But again, the problem arises with division. Let's look at a specific example:

value = 2000000000000003                // 16 digits
multiple = 2
roundingMode = RoundingMode.DOWN

ratio = divide(2000000000000003, 2)
ratio = 1000000000000001.5              // More than 16 digits, round to nearest, ties to even.
ratio = 1000000000000002                // Error. Must be 1000000000000001, rounding towards zero is required in the previous step.

ratioRounded = Decimal64Utils.roundTowardsZero(1000000000000002);
ratioRounded = 1000000000000002         // Doesn't help of course

return multiply(1000000000000002, 2)
return 2000000000000004                 // Error. Must be 2000000000000002.