Understanding Java BigDecimal Precision: Class Structure and Add Method Implementation

In financial applications, precise decimal calculations are crucial, so Java developers often use BigDecimal . This article explores how BigDecimal guarantees precision by analyzing its class definition and key internal fields.

Class Overview

public class BigDecimal extends Number implements Comparable
{
    // Unscaled value
    private final BigInteger intVal;
    // Scale (number of digits after the decimal point)
    private final int scale;
    // Cached string representation
    private transient String stringCache;
    // Compact long representation
    private final transient long intCompact;
    // Additional transient fields for precision handling
    private transient int precision;
}

Example Test Method

@Test
public void testBigDecimal() {
    BigDecimal bigDecimal1 = BigDecimal.valueOf(2.36);
    BigDecimal bigDecimal2 = BigDecimal.valueOf(3.5);
    BigDecimal resDecimal = bigDecimal1.add(bigDecimal2);
    System.out.println(resDecimal);
}

Running the test shows how the fields intVal , scale , and intCompact are populated after calling BigDecimal.valueOf(2.36) .

add Method Walk‑through

public BigDecimal add(BigDecimal augend) {
    if (this.intCompact != INFLATED) {
        if (augend.intCompact != INFLATED) {
            return add(this.intCompact, this.scale, augend.intCompact, augend.scale);
        } else {
            return add(this.intCompact, this.scale, augend.intVal, augend.scale);
        }
    } else {
        if (augend.intCompact != INFLATED) {
            return add(augend.intCompact, augend.scale, this.intVal, this.scale);
        } else {
            return add(this.intVal, this.scale, augend.intVal, augend.scale);
        }
    }
}

The overloaded private add method first computes the scale difference ( sdiff = scale1 - scale2 ) and then follows different branches:

If scales are equal, it adds the two long values directly.

If sdiff < 0 , it raises the first operand by multiplying with a power of ten, then adds.

If sdiff > 0 , it raises the second operand similarly.

When the multiplication overflows, the method falls back to BigInteger arithmetic, preserving the sign and constructing a new BigDecimal with the appropriate scale.

In the example, the call add(236, 2, 35, 1) results in sdiff = 1 , so the second operand is scaled (35 → 350) before the final addition, yielding the correct precise result.

Conclusion

BigDecimal achieves loss‑free precision by converting decimal numbers to scaled long integers (or BigInteger when necessary), performing integer arithmetic, and then applying the stored scale to produce the final decimal value.