CKTIS / Java
BigDecimal — decimal arithmetic and rounding
java.math.BigDecimal supports arbitrary-precision decimal numbers, useful for monetary calculations and similar tasks. Learn value construction, arithmetic, scale, comparison, and explicit rounding.
Version: Java SE 21; repository runtime, production runtime not attested
Syntax
new BigDecimal("12.50"); BigDecimal.valueOf(3); a.add(b); a.subtract(b); a.multiply(b); a.divide(b, 2, RoundingMode.HALF_EVEN); a.setScale(2, RoundingMode.HALF_EVEN); a.compareTo(BigDecimal.ZERO); a.stripTrailingZeros().toPlainString();java.math.BigDecimal is an immutable arbitrary-precision decimal number. BigDecimal(String) constructs an exact value from text; BigDecimal.valueOf(long) constructs one from an integer. BigDecimal.valueOf(double) uses the textual representation of the double, but cannot repair earlier calculation errors. Avoid new BigDecimal(0.1) when you intend exactly 0.1.
BigDecimal.add, BigDecimal.subtract, and BigDecimal.multiply perform addition, subtraction, and multiplication; retain the returned result. BigDecimal.ZERO is zero with scale 0. BigDecimal.compareTo compares numerical values, ignoring scale differences; equals includes scale, so it considers 2.0 and 2.00 unequal.
BigDecimal.divide without rounding parameters requires an exact, terminating decimal expansion. BigDecimal.ONE.divide(BigDecimal.valueOf(3)) throws ArithmeticException because the exact quotient has no terminating decimal expansion. In contrast, the Java expression 1 / 3 performs integer division and evaluates to 0. Division by zero also throws this exception. Supply a scale and RoundingMode when rounding is acceptable. HALF_EVEN selects the nearest value, breaking ties toward the value whose last retained digit is even.
BigDecimal.setScale sets scale, not the number of significant digits; reducing scale may require rounding. For nonnegative scales, scale is the number of decimal places. BigDecimal.stripTrailingZeros removes trailing zeros without changing the value and can produce a negative scale. BigDecimal.toPlainString renders the result without an exponent; it is not locale-sensitive currency formatting.
Examples
import java.math.BigDecimal;
import java.math.RoundingMode;
public class Main {
public static void main(String[] args) {
BigDecimal price = new BigDecimal("12.50");
BigDecimal total = price.multiply(BigDecimal.valueOf(3))
.add(new BigDecimal("2.00"))
.subtract(new BigDecimal("1.00"))
.setScale(2, RoundingMode.HALF_EVEN);
BigDecimal share = total.divide(BigDecimal.valueOf(3), 2,
RoundingMode.HALF_EVEN);
System.out.println(total.toPlainString());
System.out.println(share.toPlainString());
System.out.println(total.compareTo(BigDecimal.ZERO) > 0);
System.out.println(new BigDecimal("12.500")
.stripTrailingZeros().toPlainString());
}
}Result
38.50 12.83 true 12.5
The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.
Sources
- java.math (Java SE 21 & JDK 21)
- BigDecimal (Java SE 21 & JDK 21)
- RoundingMode (Java SE 21 & JDK 21)
- Official reference — docs.oracle.com: math / BigDecimal.html
- Official reference — docs.oracle.com: math / BigDecimal.html
- Official reference — docs.oracle.com: math / BigDecimal.html
- Official reference — docs.oracle.com: math / BigDecimal.html
- Official reference — docs.oracle.com: math / BigDecimal.html