Wrapper Classes

Java has two kinds of types. Primitive types such as int and double are simple values: a variable of type int holds the number itself. Class types such as String, Scanner, and the classes you wrote in Unit 3 describe objects, and a variable of a class type holds a reference to an object. Most of the time numbers are happiest as primitives. But some parts of Java are built to hold objects only. The next topic’s ArrayList, a list that can grow, is one of them, and it cannot hold a plain int. So Java needs a way to package a number as an object.

The package is a wrapper class: a class whose objects each hold one primitive value, “wrapped” inside an object. Picture a number sealed inside a labeled envelope. The envelope can go anywhere an object is required, and the number inside is still there to be read. For the two primitive types this course uses most, the wrapper classes are:

Notice the capital letters. int and double are primitive types and are lowercase. Integer and Double are class names, and class names start with a capital letter. Here is the difference in memory:

int laps = 12;              laps     [ 12 ]

Integer lapCount = 12;      lapCount [ ref ] ───►  Integer object
                                                    value: 12

Because Integer and Double are class types, a variable of those types can also hold null (Topic 1.13), meaning it refers to no object. An int variable can never be null.

Both classes belong to the java.lang package, the group of classes that Java makes available to every program automatically. String and Math are in java.lang too, which is why you have never imported them. Compare that with File from Topic 4.6, which lives in java.io and needs an import statement.

The Integer constants

You have already used the Integer class without knowing much about it. In Topic 1.5 you met Integer.MAX_VALUE (2,147,483,647, the largest int) and Integer.MIN_VALUE (−2,147,483,648, the smallest int). Now you can read those names fully: they are public static constants that belong to the Integer class, so you reach them through the class name, just like the class variables in Topic 3.7.

They are especially useful as starting values for the minimum and maximum algorithms from Topic 4.5. To find the smallest value, you need a starting “smallest so far” that any real value will beat. No int is larger than Integer.MAX_VALUE, so the first element is always less than or equal to it.

int[] lapTimes = {74, 69, 81, 72};
int fastest = Integer.MAX_VALUE;
for (int time : lapTimes)
{
    if (time < fastest)
    {
        fastest = time;
    }
}
System.out.println(fastest);

69

Now vary the goal: find the largest value in an array of overnight low temperatures, all below zero. The starting value flips to Integer.MIN_VALUE, because no int is smaller, so the first element always beats it.

int[] lows = {-12, -5, -9};
int warmest = Integer.MIN_VALUE;
for (int low : lows)
{
    if (low > warmest)
    {
        warmest = low;
    }
}
System.out.println(warmest);

-5

warmest starts at −2,147,483,648. The first low, −12, is greater, so it replaces it. Then −5 is greater than −12, and −9 is not greater than −5. The warmest night was −5.

int[] lows = {-12, -5, -9};
int warmest = 0;
for (int low : lows)
{
    if (low > warmest)
    {
        warmest = low;
    }
}
System.out.println(warmest);

0

int[] jumps = {-3, -8, -1, -6};
int biggest = Integer.MIN_VALUE;
for (int jump : jumps)
{
    if (jump > biggest)
    {
        biggest = jump;
        System.out.println(biggest);
    }
}

-3
-1

You know what an Integer object is. How do you make one? You might expect to call a constructor with new, as with every other object so far. You do not need to. If you write Integer lapCount = 12;, the compiler sees an int value going into an Integer variable and quietly adds the code that creates an Integer object holding 12. You write a number, and Java seals it in the envelope for you.

This automatic conversion from a primitive value to an object of its wrapper class is called autoboxing (the value is put “in a box”). It converts an int to an Integer and a double to a Double. The compiler applies it in two situations:

1. A primitive value is assigned to a variable of the matching wrapper type.
2. A primitive value is passed as an argument to a method whose parameter has the matching wrapper type.

int laps = 12;
Integer lapCount = laps;
Double price = 4.75;
System.out.println(lapCount);
System.out.println(price);

12
4.75

The second situation is a method call. Here two methods have wrapper parameters. Watch lines 6, 7, and 8.

public class AutoboxParameter
{
    public static void main(String[] args)
    {
        int adaPoints = 15;
        printBadge("Ada", adaPoints);
        printBadge("Grace", 9);
        printAverage("Ada", 87.5);
    }

    public static void printBadge(String name, Integer points)
    {
        System.out.println(name + " has " + points + " points");
    }

    public static void printAverage(String name, Double average)
    {
        System.out.println(name + " averages " + average);
    }
}

Ada has 15 points
Grace has 9 points
Ada averages 87.5

On line 6, the argument adaPoints is an int, but the parameter points on line 11 is an Integer. The compiler autoboxes the value 15 into a new Integer object, and points starts out referring to it. Line 7 shows that the argument can be a literal: 9 is boxed the same way. Line 8 boxes the double 87.5 into a Double for the parameter average. Inside the methods, line 13 and line 18 join the wrapper values into a string, which shows their numbers.

You may see older code that builds a wrapper with new Integer(12). That constructor is deprecated (marked for removal) in current Java and is not used on the AP exam; let autoboxing create wrapper objects instead.

public class BoxWrongType
{
    public static void main(String[] args)
    {
        Double price = 5;
        printPrice("pencil", 2);
    }

    public static void printPrice(String item, Double price)
    {
        System.out.println(item + " costs " + price);
    }
}

BoxWrongType.java:5: error: incompatible types: int cannot be converted to Double
BoxWrongType.java:6: error: incompatible types: int cannot be converted to Double

public class BoxOptions
{
    public static void main(String[] args)
    {
        Double total = 10;
        Integer count = 3.0;
        Double average = 10.0;
        Integer score = 3.5;
    }
}

Autoboxing goes from a number to an object. The reverse is just as common. You have an Integer and you want to do math with it, store it in an int, or pass it to a method such as Math.abs that expects a plain int. Opening the envelope by hand would be tedious, so the compiler does it for you.

Unboxing is the automatic conversion from a wrapper object to its primitive value: an Integer to an int, and a Double to a double. It mirrors autoboxing, and the compiler applies it when a wrapper object is:

1. assigned to a variable of the matching primitive type, or
2. passed as an argument to a method whose parameter has the matching primitive type.

Java also unboxes a wrapper whenever you use it in arithmetic or a comparison such as <, because those operators work on primitive values.

Integer stored = 40;
int copy = stored;
int doubled = stored * 2;
Double rate = 1.5;
double rateCopy = rate;
System.out.println(copy);
System.out.println(doubled);
System.out.println(rateCopy);

40
80
1.5

Now the second situation, method parameters, using Math methods from Topic 1.11:

Integer change = -8;
System.out.println(Math.abs(change));
Double area = 49.0;
System.out.println(Math.sqrt(area));

8
7.0

Math.abs has a version with an int parameter. change is an Integer, so on line 2 it is unboxed to −8, and Math.abs returns 8. On line 4, Math.sqrt expects a double; area is unboxed to 49.0, and the square root is 7.0.

How do unboxing and the Topic 1.5 widening rule combine? Java can unbox and then widen, but it never narrows:

The second row prints 7.0:

Integer count = 7;
double asDouble = count;
System.out.println(asDouble);

The third row gives the compile error incompatible types: Double cannot be converted to int, for the same reason int stars = 4.0; fails in Topic 1.5.

Integer bestScore = null;
System.out.println("Looking up best score");
int score = bestScore;
System.out.println(score);

Looking up best score
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "java.lang.Integer.intValue()" because "<local1>" is null

Integer bestScore = null;
System.out.println("Looking up best score");
if (bestScore != null)
{
    int score = bestScore;
    System.out.println(score);
}
else
{
    System.out.println("No score yet");
}

Looking up best score
No score yet

Integer start = -6;
Integer end = 4;
int distance = Math.abs(start) + end;
Double scale = 2.5;
double scaled = scale * distance;
System.out.println(distance);
System.out.println(scaled);

10
25.0

public class BonusNull
{
    public static void main(String[] args)
    {
        Integer bonus = null;
        int base = 50;
        System.out.println("Base: " + base);
        int total = base + bonus;
        System.out.println("Total: " + total);
    }
}

Integer bonus = 0;

In Topic 3.6, a method that received a Player could call addPoints and the caller saw the change. Can the same thing happen with an Integer? Is there any way to change the number inside an Integer object?

There is not. An Integer object is immutable: once it is created, its value can never change. The same is true for every Double object. You saw this idea with String in Topic 1.15. Neither wrapper class has a single method that changes the stored number; the envelope is sealed for good.

But then how does visits = visits + 1; work when visits is an Integer? Break it into steps:

1. visits is unboxed to its int value.
2. 1 is added, giving a new int.
3. That int is autoboxed into a brand-new Integer object.
4. visits is changed to refer to the new object.

The old object is not changed. The variable just moves to a different object.

Integer visits = 3;
Integer saved = visits;
visits = visits + 1;
System.out.println(visits);
System.out.println(saved);

4
3

The same reasoning explains what happens when an Integer is passed to a method:

public class IntegerParameter
{
    public static void main(String[] args)
    {
        Integer score = 10;
        addBonus(score);
        System.out.println("Back in main: " + score);
    }

    public static void addBonus(Integer points)
    {
        points = points + 5;
        System.out.println("Inside addBonus: " + points);
    }
}

Inside addBonus: 15
Back in main: 10

On line 6, points receives a copy of the reference to the Integer holding 10. Line 12 cannot change that object, so it builds a new Integer holding 15 and stores its reference in points. As Topic 3.6 showed, assigning to a parameter changes only the parameter. score in main still refers to the object holding 10.

public static Integer addBonus(Integer points)
{
    return points + 5;
}

Comparing wrapper values

Because wrapper variables hold references, take care with ==. When one side of == is a primitive int, Java unboxes the Integer and compares the numbers. When both sides are Integer objects, == compares references, exactly like == on two String variables in Topic 2.6: it asks whether they are the same object, not whether they hold the same number. Whether two Integer variables holding equal numbers share one object depends on how Java decided to create the objects, which you cannot see in the code, so == between two wrapper objects is not a reliable test of their values. Compare the values instead, either with equals (as with strings in Topic 1.15) or by unboxing into int variables first:

Integer stored = 1000;
int goal = 1000;
System.out.println(stored == goal);
Integer first = 1000;
Integer second = 1000;
System.out.println(first.equals(second));
int firstValue = first;
int secondValue = second;
System.out.println(firstValue == secondValue);

true
true
true

Line 3 compares an Integer with an int, so stored is unboxed. Line 6 uses equals to compare two Integer objects by value. Lines 7 and 8 unbox both objects, so line 9 compares two int values.

public class ImmutableTrace
{
    public static void main(String[] args)
    {
        Integer tickets = 8;
        Integer backup = tickets;
        tickets = tickets - 3;
        sellOne(tickets);
        System.out.println(tickets);
        System.out.println(backup);
    }

    public static void sellOne(Integer count)
    {
        count = count - 1;
        System.out.println(count);
    }
}

4
5
8

In Topic 4.6 you read lines from a text file and used split to break each line into pieces. Every piece is a String, even when it looks like a number. If a line says Ada,12,88.5, the piece "12" is two characters, not the number twelve. You cannot do math with it: as Topic 1.15 showed, + with strings joins them.

String first = "12";
String second = "30";
System.out.println(first + second);
int sum = Integer.parseInt(first) + Integer.parseInt(second);
System.out.println(sum);

1230
42

Line 3 joins "12" and "30" into "1230". Line 4 first converts each string to an int, so + adds: 12 + 30 is 42.

The conversion on line 4 is done by a static method of the Integer class:

public static int parseInt(String s)

Integer.parseInt takes a String that spells a whole number and returns that number as an int. The Double class has a partner method:

public static double parseDouble(String s)

Double.parseDouble takes a String that spells a number and returns it as a double. Both are class methods (Topic 3.7), so you call them through the class name, Integer.parseInt(...) and Double.parseDouble(...), never through an object. Use them whenever a number arrives as text: a piece of a file line, a word from a Scanner’s next(), or any other String.

String line = "Ada,12,88.5";
String[] parts = line.split(",");
String name = parts[0];
int goals = Integer.parseInt(parts[1]);
double percent = Double.parseDouble(parts[2]);
System.out.println(name + " next season: " + (goals + 1));
System.out.println(percent / 2);

Ada next season: 13
44.25

Now vary the text. parseDouble accepts a whole number, and parseInt accepts a minus sign:

double price = Double.parseDouble("90");
int count = Integer.parseInt("-5");
System.out.println(price);
System.out.println(count);

90.0
-5

Double.parseDouble("90") returns the double 90.0, which prints with a decimal point. Integer.parseInt("-5") returns the negative int −5.

String hours = "7.5";
System.out.println("Reading hours");
int worked = Integer.parseInt(hours);
System.out.println(worked);

Exception in thread "main" java.lang.NumberFormatException: For input string: "7.5"

String[] cells = {"8", "15", "2.5"};
System.out.println(cells[0] + cells[1]);
int total = Integer.parseInt(cells[0]) + Integer.parseInt(cells[1]);
System.out.println(total);
double result = total * Double.parseDouble(cells[2]);
System.out.println(result);

815
23
57.5

public class SplitSpace
{
    public static void main(String[] args)
    {
        String line = "Lee, 14";
        String[] parts = line.split(",");
        System.out.println("Player: " + parts[0]);
        int points = Integer.parseInt(parts[1]);
        System.out.println("Points: " + points);
    }
}

String[] parts = line.split(", ");

A weather station saves one line per day in weather.txt: the day, the overnight low in whole degrees, and the rainfall in inches.

Mon,-3,0.5
Tue,4,1.25
Wed,-7,0.0
Thu,2,2.75

This program finds the warmest night, adds up the rain, and prints each low through a method with an Integer parameter.

import java.io.File;
import java.io.IOException;
import java.util.Scanner;

public class WeatherLog
{
    public static void main(String[] args) throws IOException
    {
        Scanner file = new Scanner(new File("weather.txt"));
        int warmestLow = Integer.MIN_VALUE;
        String warmestDay = "";
        double totalRain = 0.0;
        while (file.hasNext())
        {
            String[] parts = file.nextLine().split(",");
            int low = Integer.parseInt(parts[1]);
            double rain = Double.parseDouble(parts[2]);
            printLow(parts[0], low);
            if (low > warmestLow)
            {
                warmestLow = low;
                warmestDay = parts[0];
            }
            totalRain += rain;
        }
        file.close();
        System.out.println("Warmest night: " + warmestDay);
        System.out.println("Total rain: " + totalRain);
    }

    public static void printLow(String day, Integer low)
    {
        if (low < 0)
        {
            System.out.println(day + ": " + Math.abs(low) + " below zero");
        }
        else
        {
            System.out.println(day + ": " + low + " above zero");
        }
    }
}

Here is where each idea from the chapter appears:

Tracing the loop:

Mon: 3 below zero
Tue: 4 above zero
Wed: 7 below zero
Thu: 2 above zero
Warmest night: Tue
Total rain: 4.5

Without parseInt and parseDouble, the program would have only strings, which cannot be compared with > or added as numbers. Without Integer.MIN_VALUE, a starting value of 0 would have worked for this file only by luck (Tuesday’s low happens to be positive); a week where every night was below zero would report 0.

Every mistake in this chapter shows up as a message. Use this table to look one up.

• Integer and Double are wrapper classes in java.lang: each object holds one int or double, so a number can go where only objects are allowed. Integer.MIN_VALUE and Integer.MAX_VALUE are class constants that make safe starting values for maximum and minimum algorithms.
• Autoboxing turns an int into an Integer or a double into a Double when the value is assigned to a wrapper variable or passed to a wrapper parameter. It only boxes into the matching wrapper.
• Unboxing takes the primitive value out of a wrapper when the object is assigned to a primitive variable, passed to a primitive parameter, or used in arithmetic or a comparison. Unboxing null throws a NullPointerException.
• Wrapper objects are immutable. Arithmetic on a wrapper variable builds a new object, so aliases and the caller’s variables never see the change.
• Integer.parseInt and Double.parseDouble convert text into numbers; text that is not a number of the right kind throws a NumberFormatException.

public class ConversionSpot
{
    public static void main(String[] args)
    {
        int raw = 9;
        Integer boxed = raw;
        int squared = square(boxed);
        Double half = squared / 2.0;
        System.out.println(squared);
        System.out.println(half);
    }

    public static int square(int value)
    {
        return value * value;
    }
}

String[] entries = {"-4", "-9", "-1", "-6"};
System.out.println(entries[0] + entries[1]);
int highest = Integer.MIN_VALUE;
for (String entry : entries)
{
    int value = Integer.parseInt(entry);
    if (value > highest)
    {
        highest = value;
    }
}
System.out.println(highest);

-4-9
-1

public class HoursBug
{
    public static void main(String[] args)
    {
        String line = "Lee,7.5";
        String[] parts = line.split(",");
        Integer hours = Double.parseDouble(parts[1]);
        System.out.println(parts[0] + " worked " + hours);
    }
}

Double hours = Double.parseDouble(parts[1]);

System.out.println(Double.parseDouble("7") + Integer.parseInt("3"));

Integer total = 7;
Integer count = 2;
double average = total / count;
System.out.println(average);
double better = 1.0 * total / count;
System.out.println(better);

3.0
3.5

• I can explain how an Integer or Double object differs from an int or double, and why no import is needed. Reread
• I can choose Integer.MIN_VALUE or Integer.MAX_VALUE as the starting value for a maximum or minimum. Reread
• I can spot where Java autoboxes a primitive, and explain why an int cannot become a Double. Reread
• I can spot where Java unboxes a wrapper object, and explain why unboxing null crashes. Reread
• I can explain why a method or an alias never sees a change to an Integer or Double. Reread
• I can convert text to numbers with Integer.parseInt and Double.parseDouble, and predict a NumberFormatException. Reread