Money and exact numbers: BigDecimal and BigInteger

Ten sweets at 10 cents each cost 1.00. Add them up in Java with a double and you get 0.9999999999999999. Turn that into cents for the card payment and the shop charges 99 cents. This lesson shows where the cent goes, and how BigDecimal keeps money exact to the last digit. It ends with BigInteger, for whole numbers too big even for a long.

When 0.1 + 0.2 is not 0.3#

Start with the smallest program that shows the problem. It adds two prices, 0.1 and 0.2, and checks whether the sum is 0.3. Press Run and step through it.

The first line prints 0.30000000000000004 and the second prints false. The trouble starts before the adding, when 0.1 and 0.2 are stored: a double cannot hold either of them exactly, so the sum comes out a tiny bit off, and == compares the stored values exactly.

A cent goes missing#

One wrong digit far after the point looks harmless. Here it is in a shop. Ten sweets cost 10 cents each, and the program adds them to a total. Payment systems often want the amount as a whole number of cents, so the last lines convert the total. Step through it and watch total in the variables view.

The third sweet already makes the total 0.30000000000000004. After the fourth it looks right again, 0.4, but from the eighth sweet on it stays just below the right answer and ends at 0.9999999999999999. Times 100 that is 99.99999999999999, and the (int) cast chops off everything after the point. The program prints Total: 0.9999999999999999 and then Charged: 99 cents: one cent short on a sale of 1.00.

Why a double cannot hold 0.1#

Think about how you write numbers. Each place after the decimal point is worth a tenth of the place before it: tenths, then hundredths, then thousandths. Some fractions fit in a few places, such as a quarter, 0.25. Others never end. A third is 0.3333... with the 3s going on forever, so wherever you stop writing, the number is a little short of a third.

A double stores numbers in binary, counting in twos instead of tens. Each place after the point is worth half the place before it: halves, then quarters, then eighths, then sixteenths. A fraction built from those fits exactly. One tenth is not one of them. In binary it is 0.000110011001100110011..., with the pattern 0011 repeating forever, the same way the 3s repeat in a third.

A double keeps 53 binary digits, about 16 significant decimal digits. It cuts the endless pattern off and stores the nearest number it can. For 0.1 that is 0.1000000000000000055511151231257827021181583404541015625, a tiny bit more than one tenth.

So why does System.out.println(0.1) show 0.1? When Java prints a double, it prints the shortest decimal that leads back to the same stored value, and for this one that is 0.1. The error is still there, only hidden. Adding the stored 0.1 and the stored 0.2 lands on the double just above the one that 0.3 is stored as, and the shortest decimal for that one is 0.30000000000000004.

Type a decimal below to see the exact value its double holds, or try 0.1 + 0.2.

Numbers built from halves and quarters behave perfectly. The others pick up tiny errors:

It prints true, true, false and 0.7999999999999999.

Key idea

A double stores the nearest binary fraction to your number. Halves, quarters and eighths fit exactly. Tenths and hundredths do not, so most prices are stored a tiny bit wrong, and the errors add up as you calculate.

A first fix: count whole cents#

One way out is to avoid fractions altogether. Store every amount as a whole number of cents in a long: 10 cents is 10 and 19.99 is 1999. Whole numbers are exact, so adding and subtracting never drift. A tax of 7.5% is 75 thousandths, so this program multiplies by 75 and divides by 1000.

The total is exactly 100 cents. The tax line shows the weak spot: 7.5% of 100 cents is 7.5 cents, and whole-number division keeps only the whole part, so the program prints Tax: 7 cents and the half cent disappears without a word. With whole cents, every percentage or split needs a rounding rule written by hand. Java has a class that keeps decimals exact and makes you name the rounding rule whenever one is needed: BigDecimal.

BigDecimal: decimals that stay exact#

BigDecimal lives in the package java.math, so a file that uses it starts with import java.math.BigDecimal;. A BigDecimal stores a decimal number digit for digit, in base ten, with as many digits as it needs. Here are the ten sweets again.

It prints Total: 1.00, and the narration spells out every step: 0.10 + 0.10 is exactly 0.20, and so on up to 1.00. Three things are new.

• new BigDecimal("0.10") builds the price from text. The text holds exactly the digits you typed, so the price is exactly 0.10.
• BigDecimal.ZERO is a ready-made zero, a constant like Math.PI. There are also BigDecimal.ONE and BigDecimal.TEN.
• total.add(price) adds with a method call. Java's + cannot add two BigDecimal objects, so BigDecimal has a method for each kind of arithmetic.

The total keeps two decimal places, 1.00, because the price was written with two. The section on scale explains the rule.

Make it from a String#

There are several ways to make a BigDecimal, and one of them brings the double problem straight back. Compare them:

It prints 0.1, then 0.1000000000000000055511151231257827021181583404541015625, then 0.1, 19.99 and 3. Line by line:

• new BigDecimal("0.1") reads the digits from text, so it holds exactly 0.1. Use it for amounts you write in your code or read from a file or a form.
• new BigDecimal(0.1) takes a double. The double 0.1 is already a little more than 0.1 by the time the constructor sees it, and this constructor keeps every digit of the stored value.
• BigDecimal.valueOf(0.1) also takes a double, but first turns it into the text that println would show, "0.1", and reads that. Use it when a value reaches you as a double and you cannot change that.
• BigDecimal.valueOf(1999, 2) means 1999 with the point moved 2 places to the left: 19.99. It suits amounts kept as whole cents.
• BigDecimal.valueOf(3) makes a whole number, handy for quantities.

Methods instead of operators#

Each operator you would use on a double has a matching method:

Here is a basket: three items at 19.99, with a coupon for 5.00 off.

It prints Subtotal: 59.97, To pay: 54.97 and Price is still 19.99. Joining a BigDecimal to a string with + works as for any object: Java calls its toString. The last line shows that calling multiply on price left price as it was.

A BigDecimal never changes#

Like a String, a BigDecimal is immutable: once made, it never changes. Each method hands back a new BigDecimal holding the answer. Decide what this program prints before you run it.

It prints 5.00 and then 7.50. The line total.add(delivery); works out 7.50 and throws the answer away, because nothing stores it. Only total = total.add(delivery); keeps it. The compiler accepts the first form without a word (some editors warn about it), which makes it a common BigDecimal bug.

Key idea

Make amounts from strings, and keep the result of every calculation: add, subtract, multiply and divide return a new BigDecimal and leave the one you called them on alone.

Scale: how many digits after the point#

Inside, a BigDecimal is two whole numbers. The unscaled value is all of its digits written as one whole number, and the scale says how many of those digits come after the decimal point. So 19.99 is the unscaled value 1999 with scale 2. The precision is how many digits the unscaled value has.

Scale is why "2.50" keeps its last zero: the text had two decimal places, so the number does too. On a price tag that is what you want. Each part has a method:

It prints 1999, 2 and 4 for the price, then 2 3 for the fee.

The scale of a result#

Adding or subtracting gives the larger of the two scales, so 19.99 plus 5 is 24.99. Multiplying adds the two scales together, because hundredths times hundredths are ten-thousandths. That is how a tax calculation grows extra places. Step through this one:

59.97 has scale 2 and the rate 0.08 has scale 2, so the tax comes out with scale 4: 4.7976 has scale 4. Nobody can pay 4.7976, so the next line rounds it to cents, and the program prints 4.80 has scale 2 and Total: 64.77.

setScale: rounding to a number of places#

tax.setScale(2, RoundingMode.HALF_UP) returns a new BigDecimal with 2 decimal places, rounded by the rule HALF_UP: the school rule, which rounds up when the first digit you drop is 5 or more. The next section covers the other rules. RoundingMode is an enum in java.math, so it needs its own import. The name setScale sounds like it changes the object, but the BigDecimal you call it on keeps its old scale. Store the result.

Leave the rounding mode out and setScale does only the jobs that need no rounding. Adding zeros is fine. Dropping a digit that is not zero throws an ArithmeticException:

It prints 2.50, then java.lang.ArithmeticException: Rounding necessary. Printing the exception e shows its full class name and its message, the same text you would see if the exception crashed the program.

Rounding modes#

Rounding 2.45 to one decimal place means choosing one of its two neighbours, 2.4 or 2.5, and 2.45 sits exactly halfway between them. The school rule sends a tie up, but that is only one reasonable rule among several. Java's RoundingMode enum names eight. Here is what each one does to a few numbers:

The modes come in groups. UP and DOWN think about distance from zero, so they treat -2.5 like 2.5 with a minus sign. CEILING and FLOOR think about the number line, where up means toward the bigger number, so CEILING turns -2.5 into -2. The three HALF modes pick the nearer neighbour and only disagree on a tie. UNNECESSARY is a promise that no rounding is needed: if a digit would be lost, it throws an ArithmeticException instead.

This loop works out the first three number columns of the table in Java. RoundingMode.values() lists the modes in order, as it does for any enum:

It prints one line per mode, matching the table: UP gives 3, -3 and 2.5, and so on down to HALF_EVEN, which gives 2, -2 and 2.4. The continue skips UNNECESSARY, which would throw on all three numbers.

HALF_EVEN, or banker's rounding#

HALF_EVEN breaks a tie by going to the neighbour whose last digit is even: 2.5 becomes 2, 3.5 becomes 4, and 2.45 becomes 2.4. That looks odd until you round many numbers and add them up. HALF_UP sends every tie upward, so over thousands of roundings the total drifts up. HALF_EVEN sends about half of the ties up and half down, so the drift cancels out.

The four amounts add up to 8.0. Rounded with HALF_UP they become 1, 2, 3 and 4, which add up to 10. Rounded with HALF_EVEN they become 0, 2, 2 and 4, which add up to 8, the true total.

The documentation of RoundingMode notes that HALF_EVEN is sometimes called banker's rounding, and that, on average, it keeps the total error smallest when you round over and over. Most double arithmetic in Java rounds the same way when it fits a result into the nearest value a double can store.

Try your own numbers. Type a decimal, choose how many places to keep, and read each mode's answer with the reason for it. The two dots beside an answer show whether it went to the smaller or the larger neighbour on the number line.

Dividing: when the digits never end#

Adding, subtracting and multiplying two exact decimals always gives an exact decimal with a known number of places. Division does not. 100 divided by 4 is 25, but 100 divided by 3 is 33.333... with 3s forever, the same kind of problem the double had with a tenth. BigDecimal refuses to guess where to stop:

Dividing by 4 prints 25.00 and dividing by 8 prints 12.50, since both answers end. Dividing by 3 throws java.lang.ArithmeticException: Non-terminating decimal expansion; no exact representable decimal result. In plain words: the digits of the answer go on forever, so no BigDecimal can hold it exactly.

The fix is to say how many places you want and how to round. bill.divide(people, 2, RoundingMode.HALF_UP) gives the answer to 2 decimal places, rounded with HALF_UP:

Each of the three friends pays 33.33, and together they pay 99.99. The bill was 100.00, so one cent is left over. No rounding mode can cut 100.00 into three equal shares of whole cents: someone has to pay a cent more than the others.

1import java.math.BigDecimal;
2import java.math.RoundingMode;
3 
4public class Main {
5    public static void main(String[] args) {
6        split(new BigDecimal("100.00"), 3);
7        split(new BigDecimal("10.00"), 4);
8    }
9 
10    static void split(BigDecimal bill, int people) {
11        BigDecimal count = BigDecimal.valueOf(people);
12        // TODO: each share, rounded down to whole cents
13        BigDecimal share = BigDecimal.ZERO;
14        // TODO: what is left: the bill minus share times count
15        BigDecimal leftover = BigDecimal.ZERO;
16 
17        System.out.println("First person pays " + share.add(leftover));
18        System.out.println("Everyone else pays " + share);
19    }
20}

equals and compareTo#

Is 2.0 the same amount as 2.00? As numbers, yes. As BigDecimal objects they differ: 2.0 is the unscaled value 20 with scale 1, and 2.00 is 200 with scale 2. Java gives you a method for each view. compareTo compares the values and returns 0 when they are equal. equals compares the values and the scales. Predict what this prints:

It prints false, 0 and 2 1. A HashSet decides what counts as a duplicate with hashCode and equals, as you saw in equals, hashCode and toString. The two scales give two different hash codes and equals says false, so the set keeps both. A TreeSet sorts with compareTo instead, which calls the two equal, so it keeps only the first one, 2.0.

The documentation calls this an ordering that is inconsistent with equals, and warns you to take care when BigDecimal values go into a sorted set or become the keys of a sorted map.

Most questions about money are value questions. Here is a customer's account after they pay what they owe, and a wallet checked against a price:

The balance prints as 0.00. balance.equals(BigDecimal.ZERO) is false, because BigDecimal.ZERO has scale 0 and the balance has scale 2, while balance.compareTo(BigDecimal.ZERO) == 0 is true. signum() returns -1, 0 or 1 for a negative number, zero or a positive number, which makes it a short way to ask about zero. The last line prints true: a wallet of 20 covers a price of 19.99, and compareTo(...) >= 0 stands in for >=.

Key idea

To ask whether two amounts are the same number, write a.compareTo(b) == 0. Put <, >, <=, >= or != in place of == to ask the other questions. equals also checks the scale.

Printing money#

System.out.printf prints text with blanks in it, filled in from the values that follow. Its first argument is a format string. Inside it, %.2f is a blank for a number shown with exactly 2 decimal places, %d a blank for a whole number, %s a blank for any value as text, and %n ends the line. String.format takes the same arguments and returns the text instead of printing it.

It prints 0.30, 0.30000000000000004, then Total: 64.77 twice and Total: 64.76, and last 4.99 x 3 = 14.97.

Look at the first two lines. printf rounded only the text it printed, and the variable sum still holds 0.30000000000000004. %.2f always rounds with HALF_UP. setScale does the same job with the rounding mode of your choice, and it gives you a value you can keep calculating with. Its toString prints exactly that many places.

BigInteger: whole numbers with no ceiling#

A long holds whole numbers up to 9223372036854775807. As wrapper classes showed, going past the top wraps around to the most negative value, and Java does not warn you. BigInteger, also in java.math, is a whole number with no fixed limit: it grows to as many digits as the answer needs.

The long prints 9223372036854775807, then wraps to -9223372036854775808 when you add 1. The BigInteger carries on to 9223372036854775808. BigInteger.valueOf turns a long into a BigInteger, and BigInteger.ONE is a ready-made 1, next to ZERO, TWO and TEN.

Factorials grow fast. 25 factorial, written 25!, is 1 × 2 × 3 × ... × 25. This program works it out twice, once in a long and once in a BigInteger. Step through it and watch smallFactorial when i reaches 21: 21! is bigger than any long, and the value turns negative.

The long ends at 7034535277573963776, a wrong answer that looks believable. The BigInteger gives the real 25!, 15511210043330985984000000. The last line raises 2 to the 100th power with pow: 1267650600228229401496703205376.

BigInteger works like BigDecimal. It never changes, and you calculate with add, subtract, multiply, divide, mod and pow. Its divide drops the remainder, the way / does on two int values. It has no scale, so its equals and compareTo always agree. To make one from a number too long to write as a long, pass the digits as text: new BigInteger("123456789012345678901234567890"). Programs use it for exact answers to counting problems, and in cryptography, where keys are numbers hundreds of digits long.

Further reading#

• java.math.BigDecimal in the Java SE 25 API documentation, with the rules for scale, rounding, equals and compareTo
• java.math.RoundingMode in the Java SE 25 API documentation, with a table of every mode on ten sample numbers
• java.math.BigInteger in the Java SE 25 API documentation
• Floating-point types and values, section 4.2.3 of the Java Language Specification, on how float and double follow the IEEE 754 standard