Comprehensive Guide to Java BigDecimal: Overview, Constructors, Common Methods, Formatting, and Pitfalls

1. BigDecimal Overview

Java provides the java.math.BigDecimal class for precise calculations with numbers that exceed the 16‑digit precision of double . While float and double handle typical floating‑point numbers, they lose precision for many decimal values, so BigDecimal should be used when exact results are required.

Creating a BigDecimal object cannot use the usual arithmetic operators ( + - * / ); instead, you must call the corresponding methods, and all method arguments must also be BigDecimal instances.

2. Common Constructors

2.1 Constructors

BigDecimal(int) – creates an instance from an int value.

BigDecimal(double) – creates an instance from a double value (may introduce precision issues).

BigDecimal(long) – creates an instance from a long value.

BigDecimal(String) – creates an instance from a decimal string, preserving the exact value.

2.2 Usage Analysis

Example:

BigDecimal a = new BigDecimal(0.1);
System.out.println("a values is:" + a);
System.out.println("=====================");
BigDecimal b = new BigDecimal("0.1");
System.out.println("b values is:" + b);

Result:

a values is:0.1000000000000000055511151231257827021181583404541015625
=====================
b values is:0.1

Reason analysis:

Using the double constructor creates a BigDecimal that represents the binary approximation of the double, not the exact decimal 0.1.

The String constructor is deterministic and yields the expected exact value.

If a double must be used, prefer BigDecimal.valueOf(double) , which internally uses Double.toString(double) to avoid the unexpected binary representation.

3. Common Methods

3.1 Arithmetic Operations

add(BigDecimal) – returns the sum.

subtract(BigDecimal) – returns the difference.

multiply(BigDecimal) – returns the product.

divide(BigDecimal) – returns the quotient (may throw an exception if the division is non‑terminating).

toString() – converts the value to a string.

doubleValue() , floatValue() , longValue() , intValue() – convert to primitive types.

3.2 Comparison

Use compareTo(BigDecimal) which returns -1, 0, or 1 to indicate less than, equal, or greater than respectively.

int a = bigDecimal1.compareTo(bigDecimal2);

4. Formatting

The NumberFormat.format() method can accept a BigDecimal to format currency, percentages, or general numbers with more than 16 effective digits.

NumberFormat currency = NumberFormat.getCurrencyInstance();
NumberFormat percent = NumberFormat.getPercentInstance();
percent.setMaximumFractionDigits(3);
BigDecimal loanAmount = new BigDecimal("15000.48");
BigDecimal interestRate = new BigDecimal("0.008");
BigDecimal interest = loanAmount.multiply(interestRate);
System.out.println("贷款金额:\t" + currency.format(loanAmount));
System.out.println("利率:\t" + percent.format(interestRate));
System.out.println("利息:\t" + currency.format(interest));

Result example: 贷款金额: ￥15,000.48 利率: 0.8% 利息: ￥120.00

5. Common Exceptions

5.1 Division Exception

When a non‑terminating decimal expansion occurs, BigDecimal.divide() throws java.lang.ArithmeticException: Non-terminating decimal expansion; no exact representable decimal result .

Solution: Specify a scale and rounding mode, e.g., divide(divisor, 2) .

6. Summary

6.1 Key Points

Use BigDecimal only when exact decimal computation is required; it is slower than double . Prefer the String constructor for predictable results. Remember that BigDecimal is immutable; each arithmetic operation creates a new instance.

6.2 Utility Class Recommendation

package com.vivo.ars.util;
import java.math.BigDecimal;
/**
 * Utility class for high‑precision arithmetic operations.
 */
public class ArithmeticUtils {
    private static final int DEF_DIV_SCALE = 10;
    public static double add(double v1, double v2) {
        BigDecimal b1 = new BigDecimal(Double.toString(v1));
        BigDecimal b2 = new BigDecimal(Double.toString(v2));
        return b1.add(b2).doubleValue();
    }
    public static BigDecimal add(String v1, String v2) {
        BigDecimal b1 = new BigDecimal(v1);
        BigDecimal b2 = new BigDecimal(v2);
        return b1.add(b2);
    }
    // ... other methods for sub, mul, div, round, remainder, compare, etc.
}

The utility class provides static methods for precise addition, subtraction, multiplication, division (with configurable scale), rounding, remainder calculation, and comparison, encapsulating common BigDecimal patterns.