BigDecimal class

BigDecimal represnet immutable, arbitrary-precision signed decimal numbers.

BigDecimal is useful for monetary values. The following code shows that floating-point-based invoice calculations leading to confusing results.


import java.text.NumberFormat; 
import java.text.NumberFormat;

public class Main {
  public static void main(String[] args) {
    double total = 123.45;
    double discount = total * 0.01;
    double beforeTax = total - discount;
    double salesTax = beforeTax * 0.13;
    double result = beforeTax + salesTax;
    NumberFormat currencyFormat = NumberFormat.getCurrencyInstance();
    System.out.println("Subtotal: " + currencyFormat.format(total));
    System.out.println("Discount: " + currencyFormat.format(discount));
    System.out.println("SubTotal after discount: " + currencyFormat.format(beforeTax));
    System.out.println("Sales Tax: " + currencyFormat.format(salesTax));
    System.out.println("Total: " + currencyFormat.format(result));
  }
}

Never using float or double to represent monetary values.

The following code uses BigDecimal to do the invoice calculations


import java.math.BigDecimal;
import java.math.RoundingMode;

public class Main {
  public static void main(String[] args) {
    BigDecimal total = new BigDecimal("123.45");
    BigDecimal discountPercent = new BigDecimal("0.10");
    BigDecimal discount = total.multiply(discountPercent);
    discount = discount.setScale(2, RoundingMode.HALF_UP);
    BigDecimal beforeTax = total.subtract(discount);
    beforeTax = beforeTax.setScale(2, RoundingMode.HALF_UP);
    BigDecimal salesTaxPercent = new BigDecimal("0.05");
    BigDecimal salesTax = beforeTax.multiply(salesTaxPercent);
    salesTax = salesTax.setScale(2, RoundingMode.HALF_UP);
    BigDecimal result = beforeTax.add(salesTax);
    result = result.setScale(2, RoundingMode.HALF_UP);
    System.out.println("Subtotal: " + total);
    System.out.println("Discount: " + discount);
    System.out.println("SubTotal after discount: " + beforeTax);
    System.out.println("Sales Tax: " + salesTax);
    System.out.println("Total: " + result);
  }
}

BigDecimal class is an immutable class and represents a signed decimal number of arbitrary precision with an associated scale. BigDecimal declares three convenience constants: ONE, TEN, and ZERO. Each constant is the BigDecimal equivalent of 1, 10, and 0 with a zero scale.

static BigDecimal ONE: The value 1, with a scale of 0.
static BigDecimal TEN: The value 10, with a scale of 0.
static BigDecimal ZERO: The value 0, with a scale of 0.

BigDecimal(0.1) results in 0.100000000000000005 being stored in the instance. BigDecimal("0.1") stores 0.1 exactly.

BigDecimal defined the following Rounding mode

static int ROUND_CEILING: Round towards positive infinity.
static int ROUND_DOWN: Round towards zero.
static int ROUND_FLOOR: Round towards negative infinity.
static int ROUND_HALF_DOWN: Round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
static int ROUND_HALF_EVEN: Round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
static int ROUND_HALF_UP: Round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
static int ROUND_UNNECESSARY: No rounding is necessary.
static int ROUND_UP: Rounding mode to round away from zero.

Constructors of BigDecimal

BigDecimal(BigInteger val): Converts a BigInteger into a BigDecimal.
BigDecimal(BigInteger unscaledVal, int scale): Converts a BigInteger with scale into a BigDecimal.
BigDecimal(BigInteger unscaledVal, int scale, MathContext mc): Converts a BigInteger and an int scale into a BigDecimal, with rounding according to the context settings.
BigDecimal(BigInteger val, MathContext mc): Converts a BigInteger into a BigDecimal rounding according to the context settings.
BigDecimal(char[] in): Converts a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor.
BigDecimal(char[] in, int offset, int len): Converts a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor, while allowing a sub-array to be specified.
BigDecimal(char[] in, int offset, int len, MathContext mc): Converts a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor, while allowing a sub-array to be specified and with rounding according to the context settings.
BigDecimal(char[] in, MathContext mc): Converts a character array representation of a BigDecimal into a BigDecimal, accepting the same sequence of characters as the BigDecimal(String) constructor and with rounding according to the context settings.
BigDecimal(double val): Converts a double into a BigDecimal which is the exact decimal representation of the double's binary floating-point value.
BigDecimal(double val, MathContext mc): Converts a double into a BigDecimal, with rounding according to the context settings.
BigDecimal(int val): Converts an int into a BigDecimal.
BigDecimal(int val, MathContext mc): Converts an int into a BigDecimal, with rounding according to the context settings.
BigDecimal(long val): Converts a long into a BigDecimal.
BigDecimal(long val, MathContext mc): Converts a long into a BigDecimal, with rounding according to the context settings.
BigDecimal(String val): Converts the string representation of a BigDecimal into a BigDecimal.
BigDecimal(String val, MathContext mc): Converts the string representation of a BigDecimal into a BigDecimal, accepting the same strings as the BigDecimal(String) constructor, with rounding according to the context settings.

Methods used to do calculation


    BigDecimal abs()
    BigDecimal abs(MathContext mc)
    BigDecimal add(BigDecimal augend)
    BigDecimal add(BigDecimal augend, MathContext mc)
    BigDecimal divide(BigDecimal divisor)
    BigDecimal divide(BigDecimal divisor, int roundingMode)
    BigDecimal divide(BigDecimal divisor, int scale, int roundingMode)
    BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode)
    BigDecimal divide(BigDecimal divisor, MathContext mc)
    BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode)
    BigDecimal[] divideAndRemainder(BigDecimal divisor)
    BigDecimal[] divideAndRemainder(BigDecimal divisor, MathContext mc)
    BigDecimal divideToIntegralValue(BigDecimal divisor)
    BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc)
    BigDecimal max(BigDecimal val)
    BigDecimal min(BigDecimal val)
    BigDecimal multiply(BigDecimal multiplicand)
    BigDecimal multiply(BigDecimal multiplicand, MathContext mc)
    BigDecimal negate()
    BigDecimal negate(MathContext mc)
    BigDecimal plus()
    BigDecimal plus(MathContext mc)
    BigDecimal pow(int n)
    BigDecimal pow(int n, MathContext mc)
    BigDecimal remainder(BigDecimal divisor)
    BigDecimal remainder(BigDecimal divisor, MathContext mc)
    BigDecimal round(MathContext mc)
    BigDecimal scaleByPowerOfTen(int n)
    BigDecimal subtract(BigDecimal subtrahend)
    BigDecimal subtract(BigDecimal subtrahend, MathContext mc)

The following methods convert BigDecimal to primitive data types

byte byteValueExact(): Converts this BigDecimal to a byte, checking for lost information.
double doubleValue(): Converts this BigDecimal to a double.
float floatValue(): Converts this BigDecimal to a float.
int intValue(): Converts this BigDecimal to an int.
int intValueExact(): Converts this BigDecimal to an int, checking for lost information.
long longValue(): Converts this BigDecimal to a long.
long longValueExact(): Converts this BigDecimal to a long, checking for lost information.
short shortValueExact(): Converts this BigDecimal to a short, checking for lost information.
BigInteger toBigInteger(): Converts this BigDecimal to a BigInteger.
BigInteger toBigIntegerExact(): Converts this BigDecimal to a BigInteger, checking for lost information.
String toEngineeringString(): Using engineering notation if an exponent is needed.
String toPlainString(): Without an exponent field.
String toString(): Using scientific notation if an exponent is needed.

To Compare two BigDecimal values

int compareTo(BigDecimal val): Compares this BigDecimal with the specified BigDecimal.
boolean equals(Object x): Compares this BigDecimal with the specified Object for equality.

To Move decimal point

BigDecimal movePointLeft(int n): decimal point moved n places to the left.
BigDecimal movePointRight(int n): decimal point moved n places to the right.

Scale and precision

int precision(): Returns the precision.
int scale(): Returns the scale.
BigDecimal setScale(int newScale): Change the scale.
BigDecimal setScale(int newScale, int roundingMode): Set scale with rounding Mode.
BigDecimal setScale(int newScale, RoundingMode roundingMode): Set scale with rounding Mode.
int signum(): Returns the signum function of this BigDecimal.
BigInteger unscaledValue(): Get the unscaled value.
BigDecimal ulp(): Returns the size of an ulp(a unit in the last place).
BigDecimal stripTrailingZeros(): trailing zeros removed.

Convert double and long to BigDecimal

static BigDecimal valueOf(double val): Translates a double into a BigDecimal.
static BigDecimal valueOf(long val): Translates a long value into a BigDecimal with a scale of zero.
static BigDecimal valueOf(long unscaledVal, int scale): Translates a long unscaled value and an int scale into a BigDecimal.

Revised from Open JDK source code

Home
Java Book
Essential Classes

BigDecimal: