toString, equals, and Methods That Combine Objects

1. toString, equals, and Methods That Combine Objects

Title

Think Java 2e · Chapter 11 · Designing Classes

Sections 11.5-11.8 · pp. 190-196

2. What you will be able to do

Objectives

This lesson follows Think Java 2e, Chapter 11 (Designing Classes), Sections 11.5-11.8, pp. 190-196. Everything on these slides can be checked against those pages.

1. Write a toString method, and say why it is not static.

2. Explain what println does with an object, and why the default output is an address.

3. Distinguish identity from equivalence, and write an equals method.

4. Say why the seconds are compared with a tolerance rather than with ==.

5. Convert a static method into an instance method, and name the three changes.

6. Recognise that an object-producing method can be plausible and still wrong, and add the carrying it needs.

• 11.5 — Displaying Objects
• 11.6 — The toString Method
• 11.7 — The equals Method
• 11.8 — Adding Times

3. Retrieve before you read

Warm-up

Two things you have watched happen without being able to cause them.

4. Making a class behave like a library class

Concept

Lesson 11a built a Time class with data and constructors. It is still unusable: you cannot see inside one, compare two, or combine them. This lesson adds the three methods that fix that — and every one of them is a method the library classes already have.

• 11.5 — displaying a Time, and why printTime is not idiomatic
• 11.6 — toString, and what println really does
• 11.7 — equals: identity against equivalence
• 11.8 — add, as a static method and as an instance method — and then correctly

Downey & Mayfield, Think Java, 2nd edition (Green Tea Press / O'Reilly, 2020) — Think Java 2e, Chapter 11 (Designing Classes), Sections 11.5-11.8, pp. 190-196 — Sections 11.5-11.8, printed pages 190-196.

5. Displaying objects

Section

Section 11.5

6. A method that prints the attributes

Concept

To display Time objects we can write a method that prints the hour, minute and second. Using printTime from Section 4.4 as a starting point, this works — and printf makes it concise.

public static void printTime(Time t) {
    System.out.printf("%02d:%02d:%04.1f\n",
                      t.hour, t.minute, t.second);
}

As a reminder from Lesson 3a: use %d with integers and %f with floating-point numbers. The 02 option pads to two digits, which is what makes 9 o'clock display as 09 rather than 9.

7. Why this method is not idiomatic

Picture it

There is nothing wrong with printTime. It is simply not the shape object-oriented code takes.

There is nothing wrong with a method like printTime, but it is not consistent with object-oriented style. A more idiomatic solution is a special method called toString — and it is also strictly more useful, for the reason on the right.

8. Reading the format string

Worked example

Three specifiers with width options, which is the first time this course has needed them. Each part controls one column of the output.

System.out.printf("%02d:%02d:%04.1f\n",
                  t.hour, t.minute, t.second);

9. What does %02d do with 7?

Prediction

Width and padding.

System.out.printf("%02d", 7);

10. What println does with an object

Concept

Before writing toString, it is worth seeing what happens without one. Every object already has a toString — it just is not useful.

public static void main(String[] args) {
    Time time = new Time(11, 59, 59.9);
    System.out.println(time);
}
// Time@80cc7c0

Every object has a method called toString, and when you display an object with print or println, Java invokes it. By default it displays the type and the address — which is the same output shape as printing an array in Lesson 7a or System.out in Lesson 3a. This address can be useful for debugging if you want to keep track of individual objects.

11. A print method that cannot be reused

Trap

printTime(t);                          // prints it

String s = printTime(t);               // no - it returns void
if (printTime(t).equals(other)) { }    // no
label = "Departs at " + printTime(t);  // no

String s = time.toString();
System.out.println(time);                    // calls it for you
label = "Departs at " + time;                // and so does concatenation

12. What does println show for an object with no toString?

Prediction

The default behaviour.

Time time = new Time(11, 59, 59.9);
System.out.println(time);

13. Which specifier for which value?

Definition probe

The letter must match the type.

14. Why is printTime static and toString not?

Explain it to yourself

One takes the Time as a parameter; the other does not.

15. The toString method

Section

Section 11.6

16. Override the default representation

Concept

You can override the default behaviour by providing your own toString method. It returns a String rather than printing one, and Java invokes it whenever an object is displayed.

public String toString() {
    return String.format("%02d:%02d:%04.1f\n",
                         this.hour, this.minute, this.second);
}

instance method — A method invoked on an instance of a class, which receives that object as this. Sometimes called non-static.

The definition does not have the keyword static, because it is not a static method. It is an instance method, so called because when you invoke it, you invoke it on an instance of the class. Instance methods are sometimes called non-static, and you may see that term in an error message.

17. The three changes from printTime

Notation

The body is nearly the same. Each change turns a method that prints into a method that produces.

Everything else — the format string, the specifiers, the order of the values — is unchanged. The method was already right; only its shape needed to move.

18. Two ways to invoke it

Worked example

You can call toString directly, or let Java call it for you. Both give the same string.

Time time = new Time(11, 59, 59.9);

String s = time.toString();       // directly
System.out.println(time);         // indirectly
System.out.println("at " + time); // and through concatenation

19. What does this display?

Prediction

toString is defined and returns 11:59:59.9

Time time = new Time(11, 59, 59.9);
System.out.println("Now: " + time);

20. Where you have seen this already

Concept

Every readable output from an object in this book has been a toString. Naming it explains all of them at once.

The fourth row is why Arrays.toString(a) exists — it supplies the readable form that arrays lack. And the last two rows are the same class before and after you write six lines: toString is the cheapest improvement you can make to a class you have written.

21. Writing print inside toString

Trap

public void toString() {              // wrong return type
    System.out.printf("%02d:%02d", this.hour, this.minute);
}

public String toString() {
    return String.format("%02d:%02d:%04.1f\n",
                         this.hour, this.minute, this.second);
}

22. Static or instance method?

Definition probe

Does the method need a particular object?

23. Write toString

Fill the middle

Return the formatted time rather than printing it.

24. Why does every class get a toString?

Real world

Java gives one to every object, even though the default is barely useful.

25. The equals method

Section

Section 11.7

26. Identity against equivalence

Concept

We have seen two ways to check whether values are equal. With objects you can use either, but they are not the same.

Time time1 = new Time(9, 30, 0.0);
Time time2 = time1;
Time time3 = new Time(9, 30, 0.0);

time1 == time2      // true  - the same object
time1 == time3      // false - different objects
time1.equals(time3) // should be true - equivalent values

The definition of identity is always the same, so == always does the same thing. But the definition of equivalence is different for different objects, so objects can define their own equals methods.

27. Three variables, two objects

Picture it

The assignment operator copies references, so two of these variables refer to one object and the third refers to another.

time1 == time2 is true because they are identical — the same object. time1 == time3 is false because they are two different objects. And yet time1 and time3 represent the same time of day, so we should consider them equivalent — which is what equals is for.

28. Writing equals for Time

Worked example

By default, the equals method does the same thing as ==. For Time objects that is probably not what we want, so we provide our own.

public boolean equals(Time that) {
    final double DELTA = 0.001;
    return this.hour == that.hour
        && this.minute == that.minute
        && Math.abs(this.second - that.second) < DELTA;
}

29. What are the three comparisons?

Prediction

Two objects, three variables.

Time time1 = new Time(9, 30, 0.0);
Time time2 = time1;
Time time3 = new Time(9, 30, 0.0);

30. Why a tolerance, and why 0.001

Concept

Comparing floating-point numbers exactly fails for values that ought to be equal, which Lesson 2b demonstrated with 0.1 added ten times.

final double DELTA = 0.001;
Math.abs(this.second - that.second) < DELTA

Math.abs gives the magnitude of the difference regardless of which is larger, and DELTA is declared final because it is a fixed threshold — Lesson 3a's named constant, used exactly as intended. The value 0.001 is a judgement about how precise a second needs to be, and a different application would choose differently.

31. Relying on the default equals

Trap

// no equals method in Time
Time t1 = new Time(9, 30, 0.0);
Time t3 = new Time(9, 30, 0.0);

System.out.println(t1.equals(t3));    // false

public boolean equals(Time that) {
    final double DELTA = 0.001;
    return this.hour == that.hour
        && this.minute == that.minute
        && Math.abs(this.second - that.second) < DELTA;
}

32. == or equals?

Definition probe

Identity is always the same question; equivalence is defined per class.

33. Why the tolerance?

Prediction

Comparing doubles exactly.

// two seconds values that should be equal:
double a = 0.1 * 3;
double b = 0.3;
System.out.println(a == b);

34. Could two Times be equal without matching?

Counterexample

Equivalence is defined by the class, so it can be anything sensible.

35. Static methods and instance methods

Section

Section 11.8

36. The same work, two shapes

Concept

Suppose a film starts at 18:50 and runs for 2 hours 16 minutes. To add two Times there are two ways to write the method — as a static method taking both objects, or as an instance method invoked on one.

// static
public static Time add(Time t1, Time t2) { ... }
Time endTime = Time.add(startTime, runningTime);

// instance
public Time add(Time t2) { ... }
Time endTime = startTime.add(runningTime);

That is all there is to it. Static methods and instance methods do the same thing, and you can convert from one to the other with just a few changes.

37. Converting between the two forms

Notation

Three edits turn one into the other, and they are always the same three.

Reading a.add(b) as Time.add(a, b) with the first argument moved is the clearest way to understand what this is: it is the argument that does not appear in the parameter list.

38. Both versions, side by side

Worked example

To demonstrate the difference, the book writes both. Trace what each one does with the same two objects.

Time startTime = new Time(18, 50, 0.0);
Time runningTime = new Time(2, 16, 0.0);

// static
Time endTime = Time.add(startTime, runningTime);

// instance
Time endTime = startTime.add(runningTime);

39. How is each version invoked?

Prediction

The first argument moves in front of the dot.

public static Time add(Time t1, Time t2) { ... }
public Time add(Time t2) { ... }

40. Which form to prefer

Concept

The two are interchangeable, so the choice is about which reads better and which class the behaviour belongs to.

Math.max is static because neither argument owns the operation. startTime.add(runningTime) is an instance method because the start time is naturally the thing being added to. Both are legitimate, and every static method you have written since Chapter 4 has been static because it belonged to no object.

41. Using this in a static method

Trap

public static Time add(Time t1, Time t2) {
    Time sum = new Time();
    sum.hour = this.hour + t2.hour;    // error
    ...
}

public static Time add(Time t1, Time t2) {
    Time sum = new Time();
    sum.hour = t1.hour + t2.hour;
    sum.minute = t1.minute + t2.minute;
    sum.second = t1.second + t2.second;
    return sum;
}

42. Static or instance?

Definition probe

Does the method operate on a particular object?

43. Convert to an instance method

Fill the middle

Remove the first parameter and use this.

44. Why is main static?

Explain it to yourself

You have written it since Chapter 1 without asking.

45. Carrying, and why the first version was wrong

Section

Section 11.8, continued

46. 20:66 is not a time

Concept

Both versions of add are plausible and both are not correct. Adding 18:50 and 2:16 gives a result of 20:66 — sixty-six minutes, which no clock shows.

// 18:50:00.0  +  02:16:00.0
//   hour:   18 + 2  = 20
//   minute: 50 + 16 = 66      <- not a valid minute
//   second: 0.0 + 0.0 = 0.0

If second exceeds 59 we have to carry into the minutes column, and if minute exceeds 59 we have to carry into hour. That is the same carrying you learned for addition on paper, and it is what the method is missing.

47. Carrying, in order

Picture it

Three checks, and the order matters: seconds can push minutes over sixty, which can then push hours over twenty-four.

The order is not a preference. Carrying the seconds may push the minutes to 60, so the minute check has to come after it — which is exactly why you add from the right on paper.

48. The corrected add

Worked example

Three if statements, each handling one column. Here is the better version of the instance method.

public Time add(Time t2) {
    Time sum = new Time();
    sum.hour = this.hour + t2.hour;
    sum.minute = this.minute + t2.minute;
    sum.second = this.second + t2.second;

    if (sum.second >= 60.0) {
        sum.second -= 60.0;
        sum.minute += 1;
    }
    if (sum.minute >= 60) {
        sum.minute -= 60;
        sum.hour += 1;
    }
    if (sum.hour >= 24) {
        sum.hour -= 24;
    }
    return sum;
}

49. What does the uncorrected add produce?

Prediction

No carrying at all.

public Time add(Time t2) {
    Time sum = new Time();
    sum.hour = this.hour + t2.hour;
    sum.minute = this.minute + t2.minute;
    sum.second = this.second + t2.second;
    return sum;
}

50. Why the bug survived a reading

Concept

The original method is symmetrical, readable and obviously about adding. Everything about its appearance is reassuring.

The bottom row is the lesson. A test that does not cross a boundary cannot find a carrying bug — and Lesson 4b's rule about knowing the right answer before you test is what makes you choose 18:50 + 2:16 rather than 1:00 + 2:00.

51. Carrying in the wrong order

Trap

if (sum.minute >= 60) {          // checked first
    sum.minute -= 60;
    sum.hour += 1;
}
if (sum.second >= 60.0) {        // too late
    sum.second -= 60.0;
    sum.minute += 1;             // minute can now be 60 again
}

if (sum.second >= 60.0) {        // seconds first
    sum.second -= 60.0;
    sum.minute += 1;
}
if (sum.minute >= 60) {          // then minutes
    sum.minute -= 60;
    sum.hour += 1;
}
if (sum.hour >= 24) {            // then hours
    sum.hour -= 24;
}

52. Order the carrying checks

Ranking

A carry can trigger the next one.

53. What happens past midnight?

Prediction

The final check has no column to carry into.

if (sum.hour >= 24) {
    sum.hour -= 24;
}
// adding 20:00 and 6:00

54. What other invalid Times can exist?

Edge cases

Nothing in the class enforces valid ranges.

55. The three methods this lesson added

Comparison

Fill the blanks. All three are instance methods, and each replaces something a library class already has.

Notice that all three return rather than print or modify. That is not an accident: a method that returns can be composed, stored and tested, which is the argument from Lesson 4b applied to a class you wrote.

56. The pattern to carry away

Pattern

Converting between a static method and an instance method is three mechanical edits, and knowing them makes the meaning of this concrete.

// static: everything arrives as a parameter
public static Time add(Time t1, Time t2) {
    ... t1.hour ...
}
Time end = Time.add(start, running);

// instance: the first parameter becomes this
public Time add(Time t2) {          // 1. drop static, 2. drop t1
    ... this.hour ...               // 3. replace t1 with this
}
Time end = start.add(running);      // and the argument moves left

• toString returns a String and is invoked automatically by println and by +.
• == is identity and always means the same thing; equals is equivalence and is defined per class.
• Never compare two doubles with == — use a tolerance.
• Carry from the smallest unit upward, because each carry can trigger the next.

57. Check: toString

Check

Work it out before you click.

public String toString() {
    return String.format("%02d:%02d", this.hour, this.minute);
}

Time t = new Time(9, 5, 0.0);
System.out.println(t);

58. Check: identity against equivalence

Check

Work it out before you click.

Time a = new Time(9, 30, 0.0);
Time b = a;
Time c = new Time(9, 30, 0.0);

59. Check: carrying

Check

Work it out before you click.

// 0:59:30.0  +  0:00:45.0

60. Correct-looking code

Real world

Think Java deliberately presents an add method that is wrong, lets it look right, and then repairs it. That choice is worth noticing.

61. How sure are you?

Commit first

Commit to an answer and to your confidence.

62. Explain it to someone else

Explain it

Two minutes, drawing as you go.

63. Exit ticket

Exit ticket

One question before you close the deck.

64. Draw the whole lesson

Connect it up

One page, from memory.

65. Recap

Recap

Four sections that turn the Time class from a container into something you can display, compare and combine.

• Every object has a toString; the default shows the type and address, and you can override it.
• println and + both call toString automatically, which is why printing a Point was readable.
• toString returns a String and is not static, so it uses this and String.format rather than a parameter and printf.
• == tests identity — the same object; equals tests equivalence — the same values.
• Identity always means one thing; equivalence is defined by each class.
• Compare doubles with a tolerance, never with ==.
• A static method takes every object as a parameter; an instance method receives one as this — three edits convert between them.
• Adding fields is not enough: carry from the smallest unit upward, because each carry can trigger the next.