Wrapper classes and autoboxing

You can write ArrayList<Integer> but not ArrayList<int>. A collection stores objects, and an int is a plain value, not an object. Java solves this with a wrapper class for each primitive type: a small class whose objects each hold one value. This lesson shows how values move in and out of those objects, how much of that Java does without being asked, and the bugs that appear when you forget the objects are there.

An int is not an object#

Say you are building a music app and want to keep the length of every song in a playlist, in seconds. A list fits the job, and the lengths are whole numbers, so ArrayList<int> looks right. The compiler refuses it with unexpected type, as you saw in the ArrayList lesson, and asks for a reference type instead.

The reason is the way each kind of value is stored. An int variable holds the number itself. A variable of an object type holds a reference: an arrow to an object that lives in a separate area of memory called the heap. A collection is built to store references, one per element, so a bare number has nowhere to go.

So every primitive type has a partner class. An object of that class holds one value of the primitive type and nothing else, the way a parcel box holds one item so that it can travel through a system built for boxes. These classes are called wrapper classes, because each object wraps one value. Putting a value into its object is called boxing, and taking it back out is called unboxing.

All eight live in java.lang, the package every Java file can use without an import line. Their objects are immutable, like strings: once a wrapper object exists, the value inside it never changes. Most programs use Integer, Double, Long, Boolean and Character. Byte, Short and Float are rare.

Key idea

A wrapper object holds one primitive value, so that the value can go where only objects are allowed, such as into a collection.

Boxing and unboxing by hand#

Before Java 5, released in 2004, you wrote every conversion yourself. Doing it the long way once shows you what Java now does behind the scenes. Each wrapper class has a static method, valueOf, that boxes a value, and an instance method that unboxes it again: intValue() on an Integer, doubleValue() on a Double, booleanValue() on a Boolean, and so on.

It prints Playlist: [185, 215] and then Total seconds: 400. Integer.valueOf(seconds) builds an Integer object that holds 215, and boxed.intValue() reads the number back out into a plain int. The list only ever receives Integer objects, and lengths.get(0) hands one back, so the code calls intValue() on it before doing any arithmetic. As you step through, compare the type shown next to each variable: boxed is an Integer and back is an int, yet both show 215.

Why valueOf and not new#

Older code builds wrapper objects with a constructor, as in new Integer(215). That constructor has been deprecated since Java 9: it still works, but the documentation advises against it, and the compiler reminds you. Here is what javac prints for a file whose line 3 is Integer boxed = new Integer(215);:

A warning does not stop the program from compiling, but it is worth acting on. new always builds a fresh object. valueOf is a static factory method, so it is free to hand back an object it made earlier, and for small numbers it does. That difference decides what == says about two boxed numbers, as you will see shortly. Use valueOf, or let Java box for you.

Autoboxing: Java does it for you#

Since Java 5, the compiler writes those calls for you. Wherever an int sits where an Integer is needed, it inserts Integer.valueOf(...). That is called autoboxing. Wherever an Integer sits where an int is needed, it inserts .intValue(), which is called auto-unboxing, or just unboxing. Here is the playlist again, with every conversion left to Java:

The output is the same, and so is the work done while it runs. The compiler turned Integer boxed = 215; into Integer boxed = Integer.valueOf(215); and int back = boxed; into int back = boxed.intValue();. The objects are all still there. You just no longer see the code that makes and opens them.

The n++ row is easy to miss. A wrapper object never changes, so n++ cannot add one to the number inside it. It unboxes, adds one, boxes the result into a different Integer, and points n at that. Any other variable that pointed at the old object still sees the old number.

Boxing only fills its own wrapper#

An int boxes into an Integer, a double into a Double, and so on down the table. Java will not first turn an int into a long or a double and then box it, so an int literal cannot become a Long or a Double. Both of these lines fail to compile:

The fix is to start from a value of the right type: Long total = 0L; and Double price = 5.0;. The L makes the literal a long, as you saw in variables and types.

Java boxes only when it must#

When a method comes in two versions, one taking an int and one taking an object, Java picks the version that needs no boxing. You met the best-known case in the ArrayList lesson: on a list of numbers, remove(2) calls remove(int) and removes the item at index 2, while remove(Integer.valueOf(2)) calls remove(Object) and removes the value 2.

Key idea

Autoboxing is the compiler writing valueOf and intValue for you. The calls disappear from your code, but the objects they make are still there.

Comparing wrappers: the Integer cache#

Two Integer variables hold the same number. Does == say they are equal? Decide before you run it.

It prints true and then false. The two halves are the same code, and the only difference is 127 against 128. Two facts explain it.

First, == on two objects does not look at the numbers inside. It asks whether both variables point at the same object, exactly as it did for your own classes in the references lesson.

Second, Integer a = 127; runs Integer.valueOf(127), and valueOf keeps a store of ready-made Integer objects, one for every number from -128 to 127. This store is called the Integer cache. Ask valueOf for one of those numbers and you get the object from the store, the same one every time. Ask for any other number and it builds a new object.

So a and b both point at the one cached object for 127, and a == b is true. c and d each got a brand-new object holding 128. Two objects means c == d is false, even though both hold the same number. Try other pairs in the lab: pick two values, switch b between Integer and int, and follow the arrows.

The cache exists because small numbers are everywhere: counters, indexes, ages, months, scores in a game. Sharing one object for each of them saves building thousands of identical ones. The sharing is safe only because an Integer never changes, the same reason Java can share one copy of each string literal in the string pool you met in the strings lesson.

Comparing the numbers instead#

There are two safe ways to compare the numbers: call equals, or unbox first and compare two primitives. Run this and match each line of output to its line of code.

• c == d is false: two separate objects.
• c.equals(d) is true: the equals method of Integer compares the numbers inside.
• c.intValue() == d.intValue() is true: after unboxing there are two plain int values, and == on primitives compares values.
• c == e is true: when one side of == is a primitive, Java unboxes the other side and compares two numbers.
• c <= d && c >= d is true: <, >, <= and >= mean nothing for objects, so Java always unboxes for them. That leaves the odd result that c is both at most and at least d, yet not == to it.

Key idea

==on two wrapper objects asks “the same object?”, and the Integer cache makes the answer depend on the number. Compare wrapper values with equals, or unbox them first.

1import java.util.ArrayList;
2import java.util.List;
3 
4public class Main {
5    public static void main(String[] args) {
6        ArrayList<Integer> scores = new ArrayList<>(List.of(250, 180, 250, 90, 250));
7 
8        Integer top = scores.get(0);
9        for (Integer s : scores) {
10            if (s > top) {
11                top = s;
12            }
13        }
14 
15        int ties = 0;
16        for (Integer s : scores) {
17            // TODO: this line compares objects. Make it compare the scores.
18            if (s == top) {
19                ties++;
20            }
21        }
22        System.out.println("Top score: " + top);
23        System.out.println("Players on the top score: " + ties);
24    }
25}

Where equals still surprises#

equals is the right tool for wrapper objects, with two catches. The first comes from mixing wrapper classes. An online shop stores its order numbers as Long values, which is common, because a long can count far past the two billion an int allows.

It prints true, false, false. The literal 1002 has no L, so it is an int, and contains needs an object, so Java boxes it into an Integer. An Integer is never equal to a Long, even when both hold the same number: the equals method of Long first checks that the other object is a Long, and the one in Integer checks for an Integer. The last line fails for the same reason, since 1L boxes into a Long. The code compiles without a warning and quietly answers false. Make both sides the same type: orderIds.contains(1002L).

Two odd doubles#

The second catch involves two special double values. NaN, short for “not a number”, is what 0.0 / 0.0 gives. Dividing a double by zero never crashes the way whole-number division does; it gives a special value such as this one. NaN is the one value that is not == to itself. Java also has a negative zero, -0.0, which == treats as equal to 0.0. The equals method of Double disagrees with == about both:

The output is false, true, true, false. Double's equals compares the stored bit patterns of the two numbers, with every NaN counted as one pattern. That makes a boxed NaN equal to NaN, so a NaN put into a list can still be found there. 0.0 and -0.0 have different patterns, and they do behave differently: 1.0 / 0.0 is Infinity, while 1.0 / -0.0 is -Infinity.

Key idea

Compare wrapper objects with equals, and give both sides the same wrapper class. A Long never equals an Integer, whatever the numbers.

Unboxing null#

A variable of a wrapper type holds a reference, so it can hold null, which an int never can. Fields show the difference: an int field starts at 0, while an Integer field starts at null, following the default values from creating classes and objects.

Sometimes nullis exactly what you want. In a game, a best score of 0 is a real score, and “has not played yet” is something else. An Integer field can say both: a number, or null for no games yet. Trouble starts when that null reaches code that needs a number. This Player keeps its best score, and finishGame replaces it whenever a new score beats it. Step through it.

The first line prints Best before any game: null. Printing null is fine, because joining it to a string turns it into the text null. The crash comes on line 16, during the first game. score > bestScore needs a number, so Java unboxes bestScore by calling bestScore.intValue(), and there is no object to call it on. Java stops with this message:

NullPointerException: Cannot invoke "java.lang.Integer.intValue()" because "this.bestScore" is null

Read it slowly. It names intValue(), a method that appears nowhere in your code. Autoboxing wrote that call, and this.bestScore is the field that held null. Whenever a NullPointerException mentions intValue(), doubleValue() or booleanValue() on a line where you never called one, look for a wrapper that was null. The parts of the message are explained in reading errors and debugging.

The fix is to deal with the empty case before anything unboxes. The first game is always a new best, so test for null first:

Now it prints Best after two games: 42. In the first game bestScore == null is true, and || skips its right side when the left side is already true, so score > bestScore never runs while the field is empty. That skipping is the short-circuit rule from operators. The order matters: written the other way round, the comparison would run first and crash again.

Turning text into numbers#

Numbers often arrive as text: typed into a form, read from a file, or passed on the command line. The text "14" is two characters, and adding 1 to it joins on a third. The wrapper classes have static methods that read a number out of a String.

The first line prints 141, because + with a String joins text. After parsing, age + 1 is 15, height * 100 is 175.0, and the last line is true. The naming follows one rule: a parse method gives you a primitive, and valueOf gives you a wrapper object. Integer.valueOf(text) reads the number exactly as parseInt does and then boxes it, using the cache. Reach for parseInt unless you need the object.

When the text is not a number#

parseInt accepts an optional + or - sign followed by digits, and nothing else: no spaces, no decimal point, no commas. Anything else makes it throw a NumberFormatException, which you met in reading errors and debugging. A single space is enough:

The program stops on line 5 with NumberFormatException: For input string: " 42". The quotation marks around the text in the message show the space at the start, which is easy to miss otherwise. The fix is to tidy the text first with trim() from the strings lesson: Integer.parseInt(typed.trim()). Double.parseDouble is more forgiving and ignores spaces at both ends on its own.

A number that is too big for an int fails the same way: Integer.parseInt("3000000000") throws, because the largest int is 2147483647. Use Long.parseLong for numbers that size.

Numbers in other bases#

parseInt takes an optional second argument, the radix: the base the digits are written in. Base 10 is the default. Base 2 uses only the digits 0 and 1, and base 16 uses 0 to 9 and then the letters a to f for ten to fifteen. Colors on web pages are a common place to meet base 16: #FF8800 is three pairs of base-16 digits, one each for red, green and blue.

It prints red 255, green 136, blue 0, then 10, 1010 and 88. substring cuts out each pair, and parseInt(..., 16) reads it in base 16: FF is 15 * 16 + 15, which is 255, and 88 is 8 * 16 + 8, which is 136. Capital and small letters both work. Going the other way, Integer.toBinaryString, Integer.toHexString and Integer.toString(n, radix) write a number out in another base. A digit that does not belong to the base fails with a message that names the base: Integer.parseInt("12z", 16) throws NumberFormatException: For input string: "12z" under radix 16.

Constants and helper methods#

The smallest and largest values#

Each numeric wrapper class has two constants, MIN_VALUE and MAX_VALUE, the limits of its primitive type. They are static final fields, like Math.PI.

The first two lines are the limits of an int: 2147483647 and -2147483648, a little over two billion either way. The third line shows what happens when you go past the top. There is no error: the value wraps around to the most negative int. This is called overflow, and Java does not warn you when it happens. Long.MAX_VALUE is 9223372036854775807, about nine billion billion.

Integer.MAX_VALUE makes a good starting point when you search for the smallest value. No int is bigger, so the lowest-so-far can only go down from there, and any real reading below it takes its place straight away.

Static helpers on Integer and Character#

The wrapper classes also carry static methods that work on plain primitives. These are the ones you will use most:

A sign-up form wants to know how many letters and digits a password has:

It prints 5 letters, 2 digits, then 1 and 5. Integer.compare(5, 2) is positive because 5 is bigger. Java prints 1 here, but the documentation promises only the sign, so test the result with > 0, never with == 1. Integer.max picks the larger count.

1public class Main {
2    public static void main(String[] args) {
3        String[] typed = {"12", "7a", "", "-5", "30", "4.5", "-"};
4        int total = 0;
5        int skipped = 0;
6        for (String t : typed) {
7            if (isWholeNumber(t)) {
8                total += Integer.parseInt(t);
9            } else {
10                skipped++;
11            }
12        }
13        System.out.println("Total: " + total);
14        System.out.println("Skipped: " + skipped);
15    }
16 
17    static boolean isWholeNumber(String text) {
18        // TODO: return true only for an optional minus sign
19        // followed by one or more digits, and nothing else
20        return false;
21    }
22}

What boxing costs#

Every boxed value outside the cache is a new object, and each object takes time to build, memory to hold, and work from the garbage collector to clear away later. One box is nothing. One box on every pass of a busy loop adds up. Step through this and look at the type of total:

It prints Steps over five days: 29500, the right answer. But total is a Long, and a Long object cannot change, so total += s has to run total = Long.valueOf(total.longValue() + s); on every pass: unbox, add, then box the sum into a new Long. After the first pass the total is far past 127, so each pass makes a new object and drops the previous one. Five days cost five objects. A year of step counts taken every minute is 525,600 passes, and as many objects, all to hold one running total. Declaring long total = 0; instead keeps the total in a single primitive variable.

Choosing between the two kinds of type comes down to whether you need an object:

Further reading#

• Integer in the Java SE 25 API documentation, with valueOf and its cache, the rules of parseInt, and every constant and helper
• Boxing and unboxing conversion in the Java Language Specification, sections 5.1.7 and 5.1.8, including the rule behind the Integer cache
• Autoboxing and unboxing on dev.java, the official Java learning site
• Double in the Java SE 25 API documentation, whose opening section explains how == and equals treat NaN and -0.0