Calling Instance Methods

Suppose a sign-up form needs to know how many characters a city name has. With Math.abs(-6) from Topic 1.10, everything the method needs arrives as an argument: you hand it -6, and it hands back 6. But “how many characters?” has no single answer. It depends on which city name you mean: "Boston" has 6 characters and "Chicago" has 7. The method needs to work with the characters stored inside one particular String object.

Recall from Topic 1.12 that every object is an instance of its class and carries its own attributes. Two String objects are made from the same blueprint, but each one stores its own characters.

In plain words: some methods are questions you ask a specific object, such as “how long are you?” Each object answers using its own data, so the same question asked of two objects can get two different answers. A method like this is called an instance method: a method that is called on an object (an instance of a class) and works with that object’s own attributes. Compare it with a class method from Topic 1.10, which belongs to the class as a whole and does not work with any particular object; anything it needs from you arrives as arguments.

You can tell the two kinds apart in the documentation. A class method’s header includes the word static; an instance method’s header does not. Here are two headers you have seen in documentation:

The String method length() returns an int: the number of characters in the string the method is called on. Every character counts, including spaces and punctuation. Its parameter list is empty, because the method needs nothing from you; the characters are already inside the object. (You will meet many more String methods in Topic 1.15. This chapter explains each one when it first appears.)

String city = "Boston";
String team = "Red Sox";
System.out.println(city.length());
System.out.println(team.length());

6
7

Now change one thing: put a class method and an instance method side by side, so you can see where each one gets its data.

int distance = Math.abs(-6);
String city = "Boston";
int letters = city.length();
System.out.println(distance);
System.out.println(letters);

6
6

Both lines print 6, but for different reasons. Math.abs(-6) gets its data from the argument -6 inside the parentheses; no object is involved. city.length() gets its data from the object city refers to; the parentheses are empty because the object already holds the characters.

String city = "Boston";
int letters = String.length();
System.out.println(letters);

String first = "Ana";
String last = "de la Cruz";
System.out.println(last.length());
System.out.println(first.length());

10
3

You have now seen calls like city.length(). It is time to take that form apart, because every instance method call in Java uses it, and knowing what each piece does tells you what Java does when the call runs.

In Topic 1.10 you wrote a class name, a dot, and a method name: Math.abs(-6). The dot operator (.) connects a method name to the thing it belongs to. For a class method, that thing is the class. For an instance method, it is an object, named by a variable that refers to the object.

Here are the pieces of int letters = city.length();:

What happens when the call runs? Remember from Topic 1.12 that city holds a reference, like an address, not the object itself. Java reads the reference in city, follows it to the String object, and runs length() on that object. As with any method call (Topic 1.9), the program pauses at the call, runs the method, and then continues right where it left off, with the returned value in place of the call.

You have been using the dot operator on an object since Topic 1.1. System.out is an object whose job is printing to the screen, and println is one of its instance methods. System.out.println("Hi") calls println on that object.

String player = "Jordan";
String captain = player;
System.out.println(player.length());
System.out.println(captain.length());
captain = "Li";
System.out.println(player.length());
System.out.println(captain.length());

6
6
6
2

String song = "Happy Birthday";
int letters = song.length;
System.out.println(letters);

String pet = "Biscuit";
String other = pet;
pet = "Max";
System.out.println(other.length());
System.out.println(pet.length());

7
3

length() takes no arguments. But many questions you might ask a string need extra information. “Where is the @ in this email address?” needs to know what to look for. Instance methods handle this exactly the way the methods in Topic 1.9 did: through parameters and arguments.

Recall the rules from Topic 1.9. A method’s signature lists its parameter types, and the arguments in a call must match them in number, order, and type. A non-void method returns a value, which you must store in a variable or use in an expression; a void method returns nothing. Every one of those rules applies to instance methods. The only new part is the object in front of the dot.

Here is a second String method. Its header is int indexOf(String str). It searches the string it is called on for the text str and returns the position where that text first appears. Positions are counted from 0, so the first character is at position 0, the second at 1, and so on. If the text does not appear at all, indexOf returns -1. (Topic 1.15 explains positions fully; this is enough for now.)

String email = "sam@school.org";
int atSpot = email.indexOf("@");
int total = email.length();
int afterAt = total - atSpot - 1;
System.out.println(atSpot);
System.out.println(total);
System.out.println(afterAt);

s  a  m  @  s  c  h  o  o  l  .  o  r  g
0  1  2  3  4  5  6  7  8  9  10 11 12 13

3
14
10

Now change one thing: keep the same object but change the argument.

String email = "sam@school.org";
System.out.println(email.indexOf("s"));
System.out.println(email.indexOf("school"));
System.out.println(email.indexOf("o"));
System.out.println(email.indexOf("!"));

0
4
7
-1

"s" first appears at position 0 (the s in sam; the later s in school does not matter, because indexOf reports the first match). "school" begins at position 4. "o" first appears at position 7, inside school. "!" never appears, so the result is -1. The object stayed the same; only the argument changed, and so did the answer. An instance method’s result can depend on both the object and the arguments.

What about a void instance method? println is one: its header in the documentation is void println(String x). It does its job (printing) and returns nothing, so it cannot be used where a value is needed:

int result = System.out.println("Hello");

The compiler reports incompatible types: void cannot be converted to int. There is no value to store, so a void call must be a statement by itself.

String password = "tiger42";
password.length();
System.out.println("Password checked.");

Password checked.

String password = "tiger42";
System.out.print("Password length: ");
System.out.println(password.length());

Password length: 7

String word = "banana";
int first = word.indexOf("an");
int size = word.length();
System.out.println(first + size);
System.out.println(word.indexOf("n") * 2);
System.out.println(word.indexOf("x"));

7
4
-1

String city = "Denver";
int letters = city.length("Denver");
System.out.println(letters);

int letters = city.length();

String city = "Denver";
int letters = city.length();
System.out.println(letters);

In Topics 1.4 and 1.13 you created a Scanner with new Scanner(System.in) and read keyboard input with calls like input.nextInt(). Now you can see what those calls were: instance methods called on a Scanner object with the dot operator. A Scanner is a good second example because it behaves differently from a String in one important way.

Here are the Scanner methods this chapter uses. A token is one chunk of input text separated from the next by spaces, such as 12 or pears.

Keyboard input changes every time a program runs, which makes its output impossible to predict on paper. So the examples here use a different Scanner constructor, one that takes a String. The Scanner then reads from that text instead of the keyboard. (Recall from Topic 1.13 that a class can have several constructors with different parameter lists.) The method calls work the same way either way.

Here is the new idea. A Scanner object remembers how far it has read. Each nextInt() or next() call returns the next token and moves the object’s place forward. So calling the same method on the same Scanner twice gives two different results, because the first call changed where the object is. Calling city.length() twice always gives the same answer, because measuring a string does not change anything about it.

import java.util.Scanner;

public class ScannerTokens
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("12 7 pears");
        int first = reader.nextInt();
        int second = reader.nextInt();
        String fruit = reader.next();
        System.out.println(first + second);
        System.out.println(fruit);
        reader.close();
    }
}

19
pears

Now change one thing: use two Scanner objects and alternate between them.

import java.util.Scanner;

public class TwoScanners
{
    public static void main(String[] args)
    {
        Scanner morning = new Scanner("5 10");
        Scanner evening = new Scanner("20 40");
        System.out.println(morning.nextInt());
        System.out.println(evening.nextInt());
        System.out.println(morning.nextInt());
        System.out.println(evening.nextInt());
    }
}

5
20
10
40

Each object keeps its own place. Reading from evening on line 10 does not move morning, so line 11 continues where morning stopped and returns 10. The variable in front of the dot decides whose data the call uses and whose place moves forward.

import java.util.Scanner;

public class WrongToken
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("pears 12");
        System.out.println("Reading the count...");
        int count = reader.nextInt();
        System.out.println(count);
    }
}

Reading the count...
Exception in thread "main" java.util.InputMismatchException

import java.util.Scanner;

public class WrongTokenFixed
{
    public static void main(String[] args)
    {
        Scanner reader = new Scanner("pears 12");
        System.out.println("Reading the count...");
        String fruit = reader.next();
        int count = reader.nextInt();
        System.out.println(count);
    }
}

Reading the count...
12

import java.util.Scanner;

public class ScoreReader
{
    public static void main(String[] args)
    {
        Scanner scores = new Scanner("8 3 9");
        int a = scores.nextInt();
        int b = scores.nextInt();
        System.out.println(a - b);
        System.out.println(scores.nextInt());
    }
}

5
9

Every call so far had an object in front of the dot. But Topic 1.4 and Topic 1.13 introduced a reference variable that refers to no object at all: one holding null. Picture an address book entry with the address left blank. What happens if you try to visit it?

The dot operator works by following the reference in the variable to an object. When the variable holds null, there is nothing to follow and no object to run the method on. Java cannot carry out the call, so it throws an exception: a NullPointerException. This is a run-time error (Topic 1.1). The compiler does not catch it, because the compiler only checks that the variable’s type, String, has a length() method, and it does. Whether the variable will hold an object when that line runs is something only running the program reveals.

public class NicknameNull
{
    public static void main(String[] args)
    {
        String nickname = "Sam";
        System.out.println(nickname.length());
        nickname = null;
        System.out.println("Nickname removed.");
        System.out.println(nickname.length());
        System.out.println("Done.");
    }
}

3
Nickname removed.
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.length()" because ...
	at NicknameNull.main(NicknameNull.java:9)

Now change one thing: give nickname an empty string instead of null.

String nickname = "";
System.out.println(nickname.length());

0

No crash. "" is a real String object that happens to contain zero characters, so there is an object to call length() on, and it returns 0. null means there is no object at all.

public class CoachNull
{
    public static void main(String[] args)
    {
        String coach = null;
        String assistant = "Kim";
        System.out.println(assistant.length());
        String backup = coach;
        System.out.println(backup.length());
        System.out.println("Practice starts.");
    }
}

3
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.length()" because ...

A café’s order system receives each order as a line of text, such as "3 bagels", and prints a slip. The program below uses every idea in this chapter.

import java.util.Scanner;

public class OrderSlip
{
    public static void main(String[] args)
    {
        Scanner order = new Scanner("3 bagels");
        int quantity = order.nextInt();
        String item = order.next();
        order.close();
        System.out.print("Quantity: ");
        System.out.println(quantity);
        System.out.print("Item: ");
        System.out.println(item);
        System.out.print("Letters in item: ");
        System.out.println(item.length());
        System.out.print("Position of g: ");
        System.out.println(item.indexOf("g"));
    }
}

Quantity: 3
Item: bagels
Letters in item: 6
Position of g: 2

Notice three things:

• Each call names its object. order.nextInt() reads from the Scanner; item.length() measures the String. The variable in front of the dot decides whose data is used.
• Returned values are kept or used. The nextInt() and next() results are stored in variables; the length() and indexOf results are passed straight to println. The void call order.close() stands alone.
• Every dot had a real object behind it. If the program also declared String note = null; and called note.length(), it would print whatever came before that line and then stop with a NullPointerException, exactly as in 1.14.5.

The Watch Out boxes each taught one mistake. This table collects the messages Java gives, so you can look one up when you see it.

• An instance method is called on one specific object and works with that object’s data; its header has no static. The same method called on different objects can return different results.
• You call an instance method with the dot operator: objectVariable.methodName(arguments). Java follows the reference in the variable to the object, so two variables that share a reference call methods on the same object.
• Instance methods follow the same rules as any method: arguments must match the parameter list, a non-void result must be stored or used, and a void method is called as a statement by itself.
• Some instance methods change the object’s state. Each Scanner call such as nextInt() returns the next token and moves that Scanner forward, so repeated calls give different results.
• Calling a method on a variable that holds null compiles but throws a NullPointerException when that line runs, because there is no object to call the method on.

String code = "AB-42";
int n = code.indexOf("-");
System.out.println(n);

String a = "summer";
String b = a;
a = "fall";
int x = b.length() - a.length();
int y = b.indexOf("m") + a.indexOf("l");
System.out.println(x);
System.out.println(y);

2
4

import java.util.Scanner;

public class PizzaOrder
{
    public static void main(String[] args)
    {
        Scanner input = new Scanner("4 pizza 10");
        int slices = input.nextInt();
        String food = input.next();
        int price = input.nextInt();
        System.out.println(price / slices);
        System.out.println(food.length() * slices);
    }
}

2
20

public class MiddleName
{
    public static void main(String[] args)
    {
        String first = "Maria";
        String middle = null;
        System.out.println(first.length());
        System.out.println(middle.length());
        System.out.println("Done.");
    }
}

public class MiddleNameFixed
{
    public static void main(String[] args)
    {
        String first = "Maria";
        String middle = "Elena";
        System.out.println(first.length());
        System.out.println(middle.length());
        System.out.println("Done.");
    }
}

5
5
Done.

import java.util.Scanner;

public class SharedScanner
{
    public static void main(String[] args)
    {
        Scanner a = new Scanner("1 2 3");
        Scanner b = a;
        a.nextInt();
        System.out.println(b.nextInt());
    }
}

Check each statement. If the answer is “not yet,” reread the linked subsection.

• I can tell an instance method from a class method by reading its header. Reread
• I can call an instance method on an object with the dot operator and say which object it uses. Reread
• I can pass matching arguments and store or use the value an instance method returns. Reread
• I can trace a series of Scanner calls and explain why repeated calls return different values. Reread
• I can explain why calling a method on null throws a NullPointerException and how to fix it. Reread