Math Class

Suppose a program knows the area of a square room, 144 square feet, and needs the length of one wall. You need the square root of 144. With only the operators +, -, *, /, and %, there is no clean way to get it. You could try guesses one after another, but that is a whole algorithm just to answer one small math question.

Java already has that algorithm written for you. In Topic 1.7 you learned that a library is a collection of ready-made classes, grouped into packages, and that API documentation tells you how to use them. One of those classes is Math. It holds methods for common calculations: absolute value, powers, square roots, and random numbers.

No import line needed

In Topic 1.4, using Scanner meant writing an import line at the top of the file so Java knew where to find that class. Math is different. It lives in a package named java.lang, and every class in java.lang is available by default: Java makes it visible to every program automatically. That is why you never write an import line for Math (or for System, which is also in java.lang). The classes in java.lang are the ones nearly every program needs, so Java saves you from importing them every time.

Only class methods

The second fact about Math is that it contains only class methods. In Topic 1.10 you saw that a class method has static in its header and belongs to the class itself, so you call it with the class name, a dot, and the method name. There is nothing to set up first: you write Math.sqrt(144.0) and get an answer. This fits what Math does. Finding a square root needs only the number you hand it, so there is no reason to call it on anything other than the class.

Here is the complete set of Math methods you need for this course, read from their headers. (Read past static here as Topic 1.10 taught: it marks a class method.)

Each one gets its own subsection below.

public class SquareTiles
{
    public static void main(String[] args)
    {
        double roomArea = 144.0;
        double side = Math.sqrt(roomArea);
        System.out.print("Side length: ");
        System.out.println(side);
        System.out.print("Perimeter: ");
        System.out.println(4 * side);
    }
}

Side length: 12.0
Perimeter: 48.0

Notice what line 10 shows: once Math.sqrt has returned, its result is an ordinary double that you can use in any expression. You could also skip the variable and write 4 * Math.sqrt(roomArea) directly. Java would call the method first, then multiply what it returned by 4, and print the same 48.0. A method call can sit anywhere a value of its return type can sit.

public class MissingClassName
{
    public static void main(String[] args)
    {
        double roomArea = 144.0;
        double side = sqrt(roomArea);
        System.out.println(side);
    }
}

MissingClassName.java:6: error: cannot find symbol
  symbol:   method sqrt(double)
  location: class MissingClassName

public class LowercaseMath
{
    public static void main(String[] args)
    {
        double gardenArea = 49.0;
        double side = math.sqrt(gardenArea);
        System.out.println(side);
    }
}

double side = Math.sqrt(gardenArea);

A guessing game picks the number 50. One player guesses 42 and another guesses 61. Who was closer? Subtracting gives 42 - 50 = -8 and 61 - 50 = 11. The minus sign only tells you which side of the target the guess was on; for “how close,” you want the distance, which is never negative: 8 and 11.

In plain words, you want the number without its sign. That is the absolute value: a number’s distance from zero. The absolute value of -8 is 8, the absolute value of 11 is 11, and the absolute value of 0 is 0. Math.abs computes it.

Two versions with the same name

The Math documentation lists two abs headers:

static int abs(int x)
static double abs(double x)

These are overloaded methods (Topic 1.9): the same name with different parameter types. Java picks the version whose parameter type matches the argument you pass. An int argument calls the int version, which returns an int. A double argument calls the double version, which returns a double. So the type you get back matches the type you put in. Why have two? If there were only a double version, Math.abs(-8) would hand back 8.0, and you could not store it in an int variable without a cast.

int target = 50;
int guess = 42;
int distance = Math.abs(guess - target);
System.out.println(distance);
guess = 61;
distance = Math.abs(guess - target);
System.out.println(distance);

Now change one thing: the type of the argument.

System.out.println(Math.abs(-4));
System.out.println(Math.abs(-4.0));
System.out.println(Math.abs(-3.5));
System.out.println(Math.abs(6));

4
4.0
3.5
6

-4 is an int literal, so the int version returns 4. -4.0 is a double literal, so the double version returns 4.0; the value is the same distance, but the type is double, and Java prints a double with a decimal point. The last line shows that a positive argument comes back unchanged.

int change = -15;
Math.abs(change);
System.out.println(change);

int change = -15;
change = Math.abs(change);
System.out.println(change);

int low = -8;
int high = 5;
System.out.println(Math.abs(low));
System.out.println(Math.abs(high - low));
System.out.println(Math.abs(low + high));
System.out.println(Math.abs(low / 2.0));

8
13
3
4.0

public class GapWrong
{
    public static void main(String[] args)
    {
        double start = 5.5;
        int end = 2;
        int gap = Math.abs(end - start);
        System.out.println(gap);
    }
}

error: incompatible types: possible lossy conversion from double to int

double gap = Math.abs(end - start);

double start = 5.5;
int end = 2;
double gap = Math.abs(end - start);
System.out.println(gap);

A square with sides of 7 has area 7². A savings account might grow by a factor each year for 10 years, which means raising that factor to the 10th power. For a small whole-number exponent you can multiply by hand, side * side, but 2 * 2 * 2 * 2 * 2 * 2 * 2 * 2 * 2 * 2 is long and easy to miscount, and you cannot write a repeated multiplication at all when the exponent is stored in a variable whose value you do not know in advance.

In plain words, you want “this number multiplied by itself that many times.” The number being multiplied is the base, and the count is the exponent. Math.pow computes it:

static double pow(double base, double exponent)

Take the header apart:

Both parameters are double, but you may pass int values: Java widens an int argument to a double automatically (Topic 1.5), so Math.pow(2, 10) works exactly like Math.pow(2.0, 10.0).

System.out.println(Math.pow(2, 10));
System.out.println(Math.pow(2.5, 2));

1024.0
6.25

Now change one thing: swap the two arguments.

System.out.println(Math.pow(2, 3));
System.out.println(Math.pow(3, 2));

8.0
9.0

Math.pow(2, 3) is 2 × 2 × 2 = 8, while Math.pow(3, 2) is 3 × 3 = 9. As Topic 1.9 taught, arguments are matched to parameters by position, so the first is always the base. Swapping them asks a different question. (A warning for anyone who has used a calculator: Java has no power operator. The ^ symbol means something else in Java and is not part of this course, so 2 ^ 3 does not compute 8. Use Math.pow.)

public class PowToInt
{
    public static void main(String[] args)
    {
        int side = 7;
        int area = Math.pow(side, 2);
        System.out.println(area);
    }
}

PowToInt.java:6: error: incompatible types: possible lossy conversion from double to int

int side = 7;
double area = Math.pow(side, 2);
System.out.println(area);
int wholeArea = (int) Math.pow(side, 2);
System.out.println(wholeArea);

49.0
49

System.out.println(Math.pow(3, 2) + Math.pow(2, 3));

Going the other way is just as common. If a square garden has an area of 20.25 square meters, how long is each side? You need a number that, multiplied by itself, gives 20.25. That number is the square root. Every positive number has two numbers that square to it (4.5 × 4.5 and −4.5 × −4.5 both give 20.25), but a length cannot be negative, so Math.sqrt always gives the nonnegative one: zero or positive, never negative.

static double sqrt(double x)

The header says: one double parameter (an int argument is widened), and a double return value. Treat a nonnegative argument as a precondition, the idea from Topic 1.8: no real number multiplied by itself gives a negative result, so a negative argument has no square root to return. As Topic 1.8 explained, a method does not promise to check its precondition for you. If you pass a negative number, you do not get a usable answer (what Java returns in that case is outside this course), so making sure the argument is nonnegative is your job.

double gardenArea = 20.25;
double side = Math.sqrt(gardenArea);
System.out.println(side);

double base = 6.0;
double height = 8.0;
double ladder = Math.sqrt(Math.pow(base, 2) + Math.pow(height, 2));
System.out.println(ladder);

Now change one thing: use a number that is not a perfect square, such as 44.

double root = Math.sqrt(44);
System.out.println(root);
System.out.println((int) root);
System.out.println((int) (root + 0.5));

6.6332495807108
6
7

The square root of 44 is not a whole number, so sqrt returns a long decimal. The second line casts it to int, which truncates to 6. The third line uses the rounding pattern from Topic 1.5, (int) (x + 0.5): 6.633 + 0.5 = 7.133, which truncates to 7, the nearest whole number. Results from Math methods combine with casting exactly like any other double.

double base = 6.0;
double height = 8.0;
double ladder = Math.sqrt(Math.pow(base, 2)) + Math.sqrt(Math.pow(height, 2));
System.out.println(ladder);

double a = Math.sqrt(Math.pow(5, 2) - Math.pow(3, 2));
System.out.println(a);
double b = Math.sqrt(Math.abs(9 - 25));
System.out.println(b);
System.out.println(Math.sqrt(9) + Math.sqrt(16));

4.0
4.0
7.0

Games roll dice, quizzes shuffle questions, and simulations model events that cannot be predicted, such as the weather. Everything you have written so far produces the same output every time it runs. To get unpredictable behavior, a program needs a source of random numbers: values that cannot be predicted ahead of time.

Math provides one method for this:

static double random()

The header has an empty parameter list, so the call takes no arguments: Math.random(). It returns a double. Each call returns a new value that you cannot predict, chosen from this range (the set of values that are possible):

• the smallest possible value is 0.0, and 0.0 itself can be returned;
• every return value is less than 1.0, and 1.0 itself cannot be returned.

Each end of a range is called an endpoint. An endpoint is inclusive when the value is part of the range (it can actually occur) and exclusive when it is not. So Math.random() returns a double from 0.0 inclusive up to 1.0 exclusive. Possible results include 0.0, 0.25, 0.5, and 0.9999, but never 1.0, never a negative number, and never anything bigger.

Tracing code that uses random numbers

You cannot trace Math.random() by predicting its value. Instead, ask “what if?” Pick a value the call could return, such as 0.5, and substitute it into the code. In this chapter, a value used this way is called a stand-in. (It is our name for the technique, not an official term.) Checking the smallest stand-in, 0.0, and a value just under 1.0 tells you the whole range of possible results.

double r = Math.random();
System.out.println(r - r);

Now change one thing: write Math.random() - Math.random() instead. That expression makes two calls, and each call returns its own unpredictable value, so the difference is almost never 0.0 and changes from run to run. When a program needs the same random value in two places (for example, the number rolled on a die), store it in a variable once.

public class RandomArgument
{
    public static void main(String[] args)
    {
        double roll = Math.random(6);
        System.out.println(roll);
    }
}

RandomArgument.java:5: error: method random in class Math cannot be applied to given types;
  required: no arguments
  found:    int

A weather simulation needs a random temperature from 60.0 up to 75.0 degrees. Math.random() only gives values from 0.0 up to 1.0. The values you get are useful only after you stretch and slide that small range to the one you need, and that is done with ordinary arithmetic from Topic 1.3.

In plain words, there are two moves:

1. Stretch with multiplication. Multiplying every possible value by 15 turns the range “0.0 up to 1.0” into “0.0 up to 15.0.” The width of the range becomes 15.
2. Slide with addition. Adding 60 to every possible value moves “0.0 up to 15.0” to “60.0 up to 75.0.” The width stays 15; only the position changes.

The endpoints keep their kind. 0.0 is a possible result of Math.random(), so 0.0 * 15 + 60 = 60.0 is a possible result: the low endpoint stays inclusive. 1.0 is never returned, so 75.0 is never reached: the high endpoint stays exclusive.

double r = 0.0;
System.out.println(r * 15 + 60);
r = 0.5;
System.out.println(r * 15 + 60);
r = 0.75;
System.out.println(r * 15 + 60);

60.0
67.5
71.25

To write the expression for any range, find the width first: high minus low. For 60.0 up to 75.0, the width is 75 − 60 = 15.

Now change one thing: a range that starts below zero. A game needs a random wind speed from −1.0 up to 1.0. The width is 1 − (−1) = 2, and the low end is −1, so “adding the low end” means adding −1, which is subtracting 1: Math.random() * 2 - 1.

double r = 0.0;
System.out.println(r * 2 - 1);
r = 0.25;
System.out.println(r * 2 - 1);
r = 0.75;
System.out.println(r * 2 - 1);

-1.0
-0.5
0.5

With stand-ins 0.0, 0.25, and 0.75, the results are −1.0, −0.5, and 0.5. The low endpoint −1.0 is inclusive, and the results approach 1.0 without reaching it.

double r = 0.5;
System.out.println(r + 60 * 15);
System.out.println(r * 15 + 60);

A die shows a whole number from 1 to 6, not 3.72. Many random choices need an int: a die roll, a card number, a random question number. You already have the two tools: Math.random() with arithmetic to stretch and slide, and the (int) cast from Topic 1.5, which truncates a double by chopping off everything after the decimal point.

Stretch, cast, then slide

Start with six possible results, numbered 0 through 5:

1. Math.random() * 6 gives a double from 0.0 up to 6.0 (exclusive).
2. (int) (Math.random() * 6) truncates it. Anything from 0.0 up to 1.0 becomes 0, anything from 1.0 up to 2.0 becomes 1, and so on up to anything from 5.0 up to 6.0, which becomes 5. Since 6.0 is never reached, 6 is impossible. The results are the six int values 0, 1, 2, 3, 4, 5.
3. Adding 1 slides them to 1, 2, 3, 4, 5, 6.

Notice what the cast does to the endpoints. In the double range, 6.0 was an exclusive endpoint. After truncating, the int results run from 0 to 5 with both endpoints inclusive: 0 and 5 really can occur. When you describe an int range, say which whole numbers are possible.

The general pattern for a random int from low to high, both inclusive, is:

(int) (Math.random() * (high - low + 1)) + low

Why high - low + 1? It is the count of whole numbers in the range, and the multiplier must equal the count, because truncating Math.random() * count produces exactly count different values, 0 through count - 1. From 1 to 6 the count is 6 − 1 + 1 = 6. Without the + 1, you would get one value too few and the high end could never occur.

double r = 0.0;
System.out.println(r * 6);
System.out.println((int) (r * 6) + 1);
r = 0.25;
System.out.println(r * 6);
System.out.println((int) (r * 6) + 1);
r = 0.5;
System.out.println(r * 6);
System.out.println((int) (r * 6) + 1);
r = 0.875;
System.out.println(r * 6);
System.out.println((int) (r * 6) + 1);

0.0
1
1.5
2
3.0
4
5.25
6

Now change the range: a random int from 10 to 20, both inclusive. The count is 20 − 10 + 1 = 11, so the expression is (int) (Math.random() * 11) + 10. Check the high end with the stand-in 0.999, a value close to 1.0, and compare the version that forgets the + 1:

double r = 0.999;
System.out.println((int) (r * 11) + 10);
System.out.println((int) (r * 10) + 10);

20
19

With * 11, 0.999 × 11 = 10.989, which truncates to 10, plus 10 is 20: the high end is reachable. With * 10, 0.999 × 10 = 9.99, which truncates to 9, plus 10 is 19, and no stand-in can ever produce 20. That version gives 10 through 19 only.

Both endpoints were inclusive in that problem. When a problem says “from 10 up to but not including 20,” the high endpoint is exclusive, so the possible values are 10 through 19 and the count is 10. Always decide first which whole numbers are allowed, then count them.

int roll = (int) Math.random() * 6 + 1;
System.out.println(roll);

int winner = (int) (Math.random() * 50);

int winner = (int) (Math.random() * 50) + 1;

A treasure-hunt game hides treasure at a random spot on a grid. Each coordinate is a random int from −5 to 5 inclusive. The player stands at (1, 2). The game reports two distances: the number of blocks to walk along the grid lines (horizontal distance plus vertical distance), and the straight-line distance “as the crow flies.” Here are the lines that do the work:

int treasureX = (int) (Math.random() * 11) - 5;
int treasureY = (int) (Math.random() * 11) - 5;
int playerX = 1;
int playerY = 2;
int blocks = Math.abs(treasureX - playerX) + Math.abs(treasureY - playerY);
double distance = Math.sqrt(Math.pow(treasureX - playerX, 2) + Math.pow(treasureY - playerY, 2));

Choosing the range (1.11.7). From −5 to 5 inclusive there are 5 − (−5) + 1 = 11 whole numbers, so the multiplier is 11. Truncating gives 0 through 10, and sliding by −5 gives −5 through 5. Each coordinate makes its own call, so the two coordinates are independent random values (1.11.5).

Tracing with stand-ins. We cannot predict the real values, so suppose the two calls returned 0.85 and 0.3:

double rx = 0.85; // stand-in for the first Math.random() call
double ry = 0.3;  // stand-in for the second Math.random() call
int treasureX = (int) (rx * 11) - 5;
int treasureY = (int) (ry * 11) - 5;
int playerX = 1;
int playerY = 2;
int blocks = Math.abs(treasureX - playerX) + Math.abs(treasureY - playerY);
double distance = Math.sqrt(Math.pow(treasureX - playerX, 2) + Math.pow(treasureY - playerY, 2));
System.out.println(treasureX);
System.out.println(treasureY);
System.out.println(blocks);
System.out.println(distance);

4
-2
7
5.0

Why each method (1.11.2 to 1.11.4). The vertical difference is −4, but nobody walks “negative 4 blocks,” so Math.abs turns each difference into a distance. blocks stays an int because both abs calls receive int arguments. The straight-line distance squares each difference with Math.pow, which also makes the sign disappear (−4 squared is 16), adds them, and takes one square root of the whole sum, never one per piece. Because pow and sqrt return double values, distance must be a double.

Checking the extremes. With stand-in 0.0 for both calls, the treasure is at (−5, −5), the low corner. With values just under 1.0 the coordinates are 5, the high corner. Every whole-number point on the grid between them is possible.

Every mistake in this chapter falls into one of two groups: the compiler stops you, or the program runs and quietly gives a wrong result. Use this table to go from what you see to its cause.

• Math is in the java.lang package, so it is available in every program without an import line. It contains only class methods, called as Math.methodName(...).
• Math.abs returns a value’s distance from zero. It is overloaded: an int argument gives an int, a double argument gives a double.
• Math.pow(base, exponent) and Math.sqrt(x) always return a double. Argument order matters for pow, and sqrt returns the nonnegative root of a nonnegative argument.
• A Math call is an expression: store or use its return value, and when calls are nested, Java evaluates them from the inside out. The methods never change their arguments.
• Math.random() returns an unpredictable double from 0.0 (inclusive) up to 1.0 (exclusive). Trace it with stand-in values, especially 0.0 and a value just under 1.0.
• Multiply to set the width and add to set the starting point: Math.random() * width + low for a double, and (int) (Math.random() * count) + low for an int, where count is high - low + 1 when both ends are included.

double a = Math.abs(-3);
System.out.println(a);

int b = Math.sqrt(16);

int side = 3;
double hyp = Math.sqrt(Math.pow(side, 2) + Math.pow(4, 2));
System.out.println(hyp);
System.out.println(Math.abs(side - 10));
System.out.println((int) Math.pow(2, 5) / 3);
System.out.println(Math.pow(2, 5) / 3);

5.0
7
10
10.666666666666666

double areaA = 9.0;
double areaB = 25.0;
double side = Math.sqrt(areaA - areaB);

double areaA = 9.0;
double areaB = 25.0;
double side = Math.sqrt(Math.abs(areaA - areaB));
System.out.println(side);

double temp = Math.random() * 30 - 10;

double temp = Math.random() * 40 - 10;

double r = 0.0;
System.out.println(r * 40 - 10);
r = 0.5;
System.out.println(r * 40 - 10);
r = 0.999;
System.out.println(r * 40 - 10);

double r = 0.3;
System.out.println((int) (r * 2) * 2 - 1);
r = 0.7;
System.out.println((int) (r * 2) * 2 - 1);

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

• I can explain why Math needs no import line and why its methods are called with the class name. Reread
• I can predict the value and the type of a Math.abs call. Reread
• I can evaluate Math.pow and explain why it returns a double. Reread
• I can evaluate nested Math calls from the inside out. Reread
• I can state which values Math.random() can return and which endpoint is exclusive. Reread
• I can write and check the range of a random double expression. Reread
• I can find the possible values of a random int expression and spot an off-by-one error. Reread