Calling Class Methods

Suppose you need the square root of 49 in a program. Back in Topic 1.7 you read the documentation for Java’s Math class, and in Topic 1.9 you read its method headers, so you know a sqrt method exists. But knowing a method exists is not enough. You need to know how to actually reach it from your code, and that depends on what kind of method it is.

Recall from Topic 1.7 that a class is like a blueprint: it can be used to make objects, also called instances of the class. Some methods do their job for one particular object. Asking for the length of a piece of text, for example, only makes sense once you say which text; Java has to know which String object you mean. You will learn to call that kind of method in Topics 1.12 to 1.14.

Finding a square root is different. sqrt needs nothing except the number you hand it as an argument. There is no particular object involved; the job belongs to the Math class as a whole. A method like this is a class method: a method that belongs to the class itself rather than to any one instance of it. You can use a class method without making any objects at all.

An everyday comparison: your school’s main office can tell anyone the date of the next holiday. You ask “the office,” not a particular student, because the answer belongs to the school as a whole. Asking a student for their locker number is different: the answer depends on which student you ask. Class methods are like the office. (The comparison stops working at one point: a Java class is not a person who answers questions; it is a set of code that runs when called.)

How can you tell a class method from other methods? Look at its header. A class method has the keyword static in its header, placed before the return type and the method name. static is the word that says “this method belongs to the class.”

public static double sqrt(double a)
public static int abs(int a)
public static double pow(double a, double b)

Now vary the class. Here is a header from the String documentation, which you saw in Topic 1.9:

public int length()

There is no static. That means length is not a class method: it belongs to each String object, which makes sense because every piece of text has its own length. You do not need to know how to call it yet; the point is that the presence or absence of static is how you tell the two kinds apart.

You have actually been writing a class method since your very first program. Look at the header every program starts with: public static void main(String[] args). It contains static, so main is a class method. That is how Java can start your program by running main without first making any object.

You know sqrt belongs to the Math class. But Math is not the only class in Java; many classes could have a method named sqrt, and you could write one yourself. When you call a class method from your program, how does Java know which class’s method you mean?

You tell it. The usual way to call a class method is to write the class name, then a dot, then the method name and its arguments in parentheses:

ClassName.methodName(arguments)

The dot is called the dot operator. Read it as “go into”: Math.sqrt(49.0) means “go into the Math class and run its sqrt method with the argument 49.0.” The class name tells Java where to look; the parts after the dot follow the rules you learned in Topic 1.9, so the arguments must match the parameter list in number, order, and type.

double side = Math.sqrt(49.0);
System.out.println(side);
double total = Math.abs(-12.5) + 2.5;
System.out.println(total);

7.0
15.0

Now change the argument types. In this version, the arguments are int values instead of double values:

int morningTemp = 12;
int afternoonTemp = 3;
int change = Math.abs(afternoonTemp - morningTemp);
System.out.println(change);
System.out.println(Math.sqrt(16));

9
4.0

Two things changed, for different reasons:

• afternoonTemp - morningTemp is 3 - 12, which is -9. The argument is an int, so Java uses the version of abs whose header is public static int abs(int a). Recall from Topic 1.9 that a method is overloaded when several methods share a name but have different signatures. abs is overloaded: there is one version for int and one for double, and Java picks the one whose parameter type matches the argument. This one returns an int, so 9 prints with no decimal point.
• sqrt has only one version, and its parameter is a double. Java can store an int in a double parameter, so the argument 16 is accepted and becomes 16.0. The return type is still double, so the result prints as 4.0, not 4.

The lesson: the type of value that comes back is the return type in the header of the method that runs. For sqrt that is always double, even when the argument looks like an int.

double root = Math.sqrt("25");
System.out.println(root);

int loss = -7;
System.out.println(Math.abs(loss));
System.out.println(Math.abs(-7.0));
System.out.println(Math.sqrt(64));

7
7.0
8.0

int square = Math.pow(5, 2);
System.out.println(square);

Real programs rarely call one method on a line by itself. A formula might need a square root of a sum of powers, which means one call sits inside another. To predict what such code prints, you need a reliable way to work out the value of each call.

Here is the rule, built from what you know about expressions (Topic 1.3) and about method calls (Topic 1.9):

1. Arguments first. Before a method runs, Java works out the value of each argument completely. If an argument is an expression, it is evaluated with the usual rules, including integer division.
2. The method runs. The parameter is given a copy of the argument’s value, and the method’s code runs.
3. The call is replaced by its return value. Once the method returns, the whole call Math.sqrt(...) acts like the value it sent back, and the rest of the expression continues with that value.

When calls are nested, apply the rule from the inside out: the inner call is an argument of the outer call, so it is finished first.

double legA = 3.0;
double legB = 4.0;
double longSide = Math.sqrt(Math.pow(legA, 2) + Math.pow(legB, 2));
System.out.println(longSide);

5.0

Now change only the type of the numbers inside an argument. The two lines below differ by one character:

System.out.println(Math.sqrt(9 / 4));
System.out.println(Math.sqrt(9.0 / 4));

1.4142135623730951
1.5

In the first line, Java evaluates the argument 9 / 4 before calling sqrt. Both numbers are int, so this is integer division and the result is 2, not 2.25. sqrt never sees 2.25; it receives 2 (as 2.0) and returns the square root of 2. In the second line, 9.0 / 4 is 2.25, and the square root of 2.25 is 1.5. The method behaved the same both times; the arguments were different because they were evaluated first.

double balance = -4.5;
Math.abs(balance);
System.out.println(balance);

double balance = -4.5;
balance = Math.abs(balance);
System.out.println(balance);

double result = Math.sqrt(Math.abs(-36)) + Math.pow(2, 3);
System.out.println(result);

14.0

int wholeRoot = Math.sqrt(30.0);
System.out.println(wholeRoot);

int wholeRoot = (int) Math.sqrt(30.0);
System.out.println(wholeRoot);

So far, every class method you have called lived in Math, while your code lived in a different class. But you can write class methods in your own classes too. In Topic 1.9 you saw methods with a header and a body; if that header includes static, the method is a class method of your class. When your own class calls its own class method, do you still need to write the class name?

You may, but you do not have to. The class a method is written in is its defining class. When the call is written inside the defining class, Java already knows which class to look in first: the one it is in. So the class name and dot are optional. When the call comes from a different class, as every call to Math from your programs does, the class name is required, because Java will not search other classes for you.

public class ShiftPlanner
{
    public static int toMinutes(int hours)
    {
        return hours * 60;
    }

    public static void main(String[] args)
    {
        int shortShift = toMinutes(4);
        int longShift = ShiftPlanner.toMinutes(9);
        System.out.println(shortShift);
        System.out.println(longShift);
    }
}

240
540

Now vary the kind of method. printDivider below is a void class method, so it is called as a statement on its own rather than inside an expression:

public class ScoreCard
{
    public static void printDivider()
    {
        System.out.println("----------");
    }

    public static void main(String[] args)
    {
        System.out.println("Round 1: 18");
        printDivider();
        System.out.println("Round 2: 24");
        ScoreCard.printDivider();
        System.out.println("Done");
    }
}

Round 1: 18
----------
Round 2: 24
----------
Done

Line 11 (printDivider();) and line 13 (ScoreCard.printDivider();) both pause main, run line 5, and return to the next line of main. The class-name rule is the same for void and non-void class methods.

public class NoClassName
{
    public static void main(String[] args)
    {
        double root = sqrt(81.0);
        System.out.println(root);
    }
}

NoClassName.java:5: error: cannot find symbol
  symbol:   method sqrt(double)
  location: class NoClassName

public class MissingStatic
{
    public int toMinutes(int hours)
    {
        return hours * 60;
    }

    public static void main(String[] args)
    {
        int shift = toMinutes(4);
        System.out.println(shift);
    }
}

This program finds straight-line distances on a city map, where each place has an across position and an up position. It defines its own class method, distance, which calls two Math class methods inside it.

public class MapDistance
{
    public static double distance(double x1, double y1, double x2, double y2)
    {
        double across = x2 - x1;
        double up = y2 - y1;
        return Math.sqrt(Math.pow(across, 2) + Math.pow(up, 2));
    }

    public static void main(String[] args)
    {
        double toLibrary = distance(0.0, 0.0, 3.0, 4.0);
        double toPark = MapDistance.distance(2.0, 1.0, 8.0, 9.0);
        System.out.print("Library: ");
        System.out.println(toLibrary);
        System.out.print("Park: ");
        System.out.println(toPark);
        System.out.print("Difference: ");
        System.out.println(Math.abs(toLibrary - toPark));
    }
}

Look at the calls first, before tracing:

Now trace. Line 12 pauses main and runs distance with x1 = 0.0, y1 = 0.0, x2 = 3.0, y2 = 4.0:

Control returns to line 12, and toLibrary holds 5.0. Line 13 runs the same method with 2.0, 1.0, 8.0, 9.0: across is 6.0, up is 8.0, and Math.sqrt(36.0 + 64.0) is Math.sqrt(100.0), so toPark holds 10.0.

Lines 14 to 17 print each label with print (which stays on the same line) and then the distance with println. On line 19, the argument toLibrary - toPark is evaluated first: 5.0 - 10.0 is -5.0. Then Math.abs(-5.0) returns 5.0, which println displays after the label from line 18:

Library: 5.0
Park: 10.0
Difference: 5.0

Every idea from the chapter appears: static marks distance as a class method, Math methods are called through the class name, arguments are evaluated before each call and each call is replaced by its return value, and the class name is optional only for the method defined in this class.

• A class method belongs to its class, not to any instance of the class, so it can be used without making an object. Its header contains static before the method name; main is one.
• The usual way to call a class method is the class name, the dot operator, the method name, and the arguments: Math.sqrt(49.0). The arguments must fit the parameter list, and the return type in the header decides the type of the result.
• To find the value of a call, evaluate its arguments first, then replace the call with its return value. Nested calls are worked out from the inside out. A non-void call whose result is not stored or used has no effect on your variables.
• Inside a method’s defining class, the class name is optional in the call. From any other class it is required, and leaving it out causes a “cannot find symbol” error.

public class Workout
{
    public static void printLaps(int laps)
    {
        System.out.print("Laps: ");
        System.out.println(laps);
    }

    public static void main(String[] args)
    {
        System.out.println("Start");
        printLaps(Math.abs(-6));
        Workout.printLaps(10 - 4 * 2);
        System.out.print("Pace: ");
        System.out.println(Math.sqrt(2.25));
    }
}

Start
Laps: 6
Laps: 2
Pace: 1.5

public class AreaHelper
{
    public double squareArea(double side)
    {
        return pow(side, 2);
    }

    public static void main(String[] args)
    {
        System.out.println(squareArea(3.0));
    }
}

public class AreaHelperFixed
{
    public static double squareArea(double side)
    {
        return Math.pow(side, 2);
    }

    public static void main(String[] args)
    {
        System.out.println(squareArea(3.0));
    }
}

System.out.println(Math.sqrt(5 / 2 * 8) + Math.abs(3 - 10));
System.out.println(Math.sqrt(5.0 / 2 * 8) + Math.abs(3 - 10));

public class PaintJob
{
    public static double wallArea(double width, double height)
    {
        return width * height;
    }

    public static double gallonsNeeded(double width, double height)
    {
        return wallArea(width, height) / 400.0;
    }

    public static void main(String[] args)
    {
        System.out.println(PaintJob.wallArea(20.0, 10.0));
        System.out.println(gallonsNeeded(20.0, 10.0));
        System.out.println(Math.abs(wallArea(5.0, 8.0) - 100.0));
    }
}

200.0
0.5
60.0

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

• I can explain what makes a method a class method and find static in its header. Reread
• I can call a class method using the class name and the dot operator. Reread
• I can work out the value of nested class method calls, evaluating arguments first. Reread
• I can explain when the class name may be left out of a call and when it is required. Reread