Card Objects, Class Variables, and compareTo

1. Card Objects, Class Variables, and compareTo

Title

Think Java 2e · Chapter 12 · Arrays of Objects

Sections 12.1-12.5 · pp. 201-208

2. What you will be able to do

Objectives

This lesson follows Think Java 2e, Chapter 12 (Arrays of Objects), Sections 12.1-12.5, pp. 201-208. Everything on these slides can be checked against those pages.

1. Explain what it means to encode a set of values, and why integers were chosen over Strings.

2. Use an array of Strings to decode an integer back into a word.

3. Distinguish a class variable from an instance variable, and say what static and final each mean.

4. Write a compareTo method returning a negative number, zero or a positive number.

5. Explain what totally ordered, partially ordered and unordered mean.

6. Make a class immutable by omitting setters and declaring the instance variables final.

• 12.1 — Card Objects
• 12.2 — Card toString
• 12.3 — Class Variables
• 12.4 — The compareTo Method
• 12.5 — Cards Are Immutable

3. Retrieve before you read

Warm-up

Two techniques from earlier chapters are about to be combined.

4. Choosing a representation

Concept

A standard deck has 52 cards, each belonging to one of four suits and one of thirteen ranks. It is clear what the instance variables should be — rank and suit — and not obvious what types they should be. That choice decides everything else in the chapter.

• 12.1 — encoding ranks and suits as integers
• 12.2 — decoding them back into words for toString
• 12.3 — class variables: one copy shared by every object
• 12.4 — compareTo, and what kind of order cards have
• 12.5 — making the class immutable

Downey & Mayfield, Think Java, 2nd edition (Green Tea Press / O'Reilly, 2020) — Think Java 2e, Chapter 12 (Arrays of Objects), Sections 12.1-12.5, pp. 201-208 — Chapter 12 opens on printed page 201.

5. Encoding ranks and suits

Section

Section 12.1

6. A mapping between numbers and things

Concept

One possibility is a String containing "Spade" for suits and "Queen" for ranks. A problem with that choice is that it would not be easy to compare cards to see which had a higher rank or suit. The alternative is to encode them as integers.

// suits              // ranks
// Clubs    -> 0      // Ace  -> 1
// Diamonds -> 1      // 2-10 -> 2 to 10
// Hearts   -> 2      // Jack -> 11
// Spades   -> 3      // Queen -> 12
//                    // King  -> 13

encode — To represent one set of values using another set of values by constructing a mapping between them.

By encode we do not mean to encrypt or translate into a secret code. We mean to define a mapping between a sequence of numbers and the things we want to represent. The numeric ranks 2 through 10 map to themselves, which keeps the mapping easy to remember.

7. The mapping is design, not code

Notation

Think Java uses a mathematical arrow for the mapping deliberately, and the reason is worth noticing.

An encoding is a design decision that the compiler cannot check. Choosing one that is easy to remember, and writing it down, is most of the work.

8. Why integers make comparison possible

Worked example

The whole argument for the integer encoding is one thing Strings cannot do. Make it concrete.

// with Strings:
"Queen" < "Jack"          // does not compile - < is for primitives
"Queen".compareTo("Jack") // positive - but that is ALPHABETICAL order

// with integers:
12 > 11                   // true, and it means Queen beats Jack

9. What card is new Card(12, 2)?

Prediction

Apply the two mappings.

// ranks: Ace 1, 2-10 themselves, Jack 11, Queen 12, King 13
// suits: Clubs 0, Diamonds 1, Hearts 2, Spades 3

10. The Card class so far

Concept

With the encoding decided, the class definition is the Chapter 11 pattern applied to two integers.

public class Card {
    private int rank;
    private int suit;

    public Card(int rank, int suit) {
        this.rank = rank;
        this.suit = suit;
    }
}

The instance variables are private: we can access them from inside this class, but not from other classes. new Card(3, 0) produces a reference to a Card representing the 3 of Clubs — and a reader who does not know the encoding cannot tell that from the call, which is a real weakness this chapter acknowledges.

11. An encoding nobody wrote down

Trap

Card c1 = new Card(3, 0);      // 3 of Clubs? or Clubs of 3?
Card c2 = new Card(0, 3);      // and this?
Card c3 = new Card(1, 2);      // Ace of Hearts, or 2 of... something?

// with the class variables from Section 12.3:
Card c = new Card(3, Card.CLUBS);

// or at minimum, a comment recording the mapping:
// suits: 0 Clubs, 1 Diamonds, 2 Hearts, 3 Spades

12. Which representation for which job?

Definition probe

Strings display well; integers compare well.

13. Why is rank 0 unused?

Prediction

Ace maps to 1, not 0.

// Ace -> 1, King -> 13
// so valid ranks are 1 to 13

14. Is the encoding arbitrary?

Socratic

Clubs could have been 3 and Spades 0.

15. Decoding for toString

Section

Section 12.2

16. An array of Strings turns a number back into a word

Concept

When you create a new class, the first step is to declare the instance variables and write constructors. A good next step is to write toString, which is useful for debugging and incremental development. To display a Card readably we have to decode the integers back into words.

String[] suits = {"Clubs", "Diamonds", "Hearts", "Spades"};

String[] ranks = {null, "Ace", "2", "3", "4", "5", "6",
                  "7", "8", "9", "10", "Jack", "Queen", "King"};

String s = ranks[this.rank] + " of " + suits[this.suit];

ranks[this.rank] means use the instance variable rank from this object as an index into the array ranks. That is Lesson 7b's value-as-index trick, used to decode rather than to count.

17. An array of references to Strings

Picture it

Each element of the array is a reference to a String object — which is exactly what Lesson 9a's picture of an object variable predicted.

The array's index order encodes the mapping: Clubs is at 0 because Clubs maps to 0. So the array is not just a lookup table — it is the one place in the program where the design decision is written down in code.

18. The null placeholder

Worked example

The ranks array has fourteen elements for thirteen ranks. The extra one is deliberate and its value is chosen carefully.

String[] ranks = {null, "Ace", "2", "3", "4", "5", "6",
                  "7", "8", "9", "10", "Jack", "Queen", "King"};

19. What does this print?

Prediction

Decode both integers.

Card card = new Card(11, 1);
System.out.println(card);

20. toString for Card

Concept

Wrapping the decoding in a toString gives the class the readable output Lesson 11b established, and it is the first thing to write after the constructor.

public String toString() {
    String[] ranks = {null, "Ace", "2", "3", "4", "5", "6",
                      "7", "8", "9", "10", "Jack", "Queen", "King"};
    String[] suits = {"Clubs", "Diamonds", "Hearts", "Spades"};

    String s = ranks[this.rank] + " of " + suits[this.suit];
    return s;
}

When we display a card, println automatically calls toString — the mechanism from Lesson 11b. Writing it early is what makes the rest of the chapter debuggable: without it, every Card prints as Card@1a2b3c4d and you cannot see what your code is doing.

21. Building the arrays on every call

Trap

public String toString() {
    String[] ranks = { ... 14 strings ... };
    String[] suits = { ... 4 strings ... };
    return ranks[this.rank] + " of " + suits[this.suit];
}

public static final String[] RANKS = { ... };
public static final String[] SUITS = { ... };

public String toString() {
    return RANKS[this.rank] + " of " + SUITS[this.suit];
}

22. How many elements does the ranks array have?

Prediction

Thirteen ranks, and a placeholder.

String[] ranks = {null, "Ace", "2", ..., "King"};

23. Decode a card

Fill the middle

Use the instance variables as indexes.

24. Why write toString so early?

Explain it to yourself

Before compareTo, before getters, before anything else.

25. Class variables

Section

Section 12.3

26. One copy, shared by every object

Concept

You have seen local variables, declared inside a method, and instance variables, declared in a class definition. Now for class variables: they are also declared in the class, before the methods, but they are identified by the keyword static — and they are shared across all instances.

public class Card {

    public static final String[] RANKS = {
        null, "Ace", "2", "3", "4", "5", "6", "7",
        "8", "9", "10", "Jack", "Queen", "King"};

    public static final String[] SUITS = {
        "Clubs", "Diamonds", "Hearts", "Spades"};

    // instance variables and constructors go here

    public String toString() {
        return RANKS[this.rank] + " of " + SUITS[this.suit];
    }
}

class variable — A variable declared within a class as static. There is only one copy, no matter how many objects there are.

Class variables are allocated when the program begins and persist until the program ends. In contrast, instance variables like rank and suit are allocated when the program creates new objects and deleted when the object is garbage-collected.

27. static and final are separate decisions

Notation

public static final String[] RANKS has three modifiers, and each one means something different.

The second note is the subtle one. final on an array reference stops you reassigning the reference — it does not stop anyone changing an element. That is a real gap, and the next hazard is about it.

28. Choosing between the three kinds of variable

Worked example

You now have three places to declare something. The deciding question is how many copies should exist and how long each should live.

public class Card {

    public static final String[] SUITS = { ... };   // one, for the class

    private int rank;                                // one per Card
    private int suit;

    public String toString() {
        String s = RANKS[this.rank];                 // one per call
        ...
    }
}

29. Which kind of variable?

Definition probe

How many copies should exist?

30. Where you have already used class variables

Concept

Every constant and method you have called on a class rather than an object was static. Naming the concept explains several things at once.

The pattern is consistent: static members are reached through the class name, because they do not belong to any object. That is also why main is static — Lesson 11b's point — and why you cannot use this inside one.

31. Thinking final protects the array's contents

Trap

public static final String[] SUITS = {"Clubs", ...};

SUITS = new String[4];      // error - the reference is final
SUITS[0] = "Wands";         // legal! the elements are not

// final: this reference will always point at this array
public static final String[] SUITS = { ... };

// if the contents must be protected, do not expose the array:
private static final String[] SUITS = { ... };
public static String suitName(int suit) {
    return SUITS[suit];
}

32. How many SUITS arrays exist?

Prediction

Fifty-two cards are created.

public static final String[] SUITS = { ... };
// then 52 Card objects are created

33. Match the modifier to its meaning

Matching

Three modifiers, three separate decisions.

34. Can a static method use an instance variable?

Edge cases

Push on what shared means.

35. The compareTo method

Section

Section 12.4

36. Comparing objects needs a method

Concept

For primitive types we can use < and > to compare values. But these operators do not work for object types. For Strings, Java provides compareTo; for classes we define, we can write our own — just as we did for equals.

public boolean equals(Card that) {
    return this.rank == that.rank
        && this.suit == that.suit;
}

This is Lesson 11b's equals, now for Card — and both instance variables are ints, so both are compared with ==. There is no double here, so no tolerance is needed.

37. Three kinds of order

Notation

Before writing compareTo, it is worth asking whether cards can be ordered at all. The answer is not naturally — which is why the method has to make a decision.

That is worth noticing as a general point: writing compareTo for a partially ordered type means imposing an order rather than discovering one, and the class's author has to choose.

38. Writing compareTo

Worked example

With suit decided as more important, the method compares suits first and falls back on ranks.

public int compareTo(Card that) {
    if (this.suit < that.suit) {
        return -1;
    }
    if (this.suit > that.suit) {
        return 1;
    }
    if (this.rank < that.rank) {
        return -1;
    }
    if (this.rank > that.rank) {
        return 1;
    }
    return 0;
}

39. What does compareTo return?

Prediction

Suit is compared first.

Card a = new Card(2, 3);    // 2 of Spades
Card b = new Card(13, 0);   // King of Clubs
a.compareTo(b)

40. Why the sign rather than the value

Concept

compareTo returns -1, 0 or 1 here, but callers should test the sign rather than the exact number — as Lesson 6b's String comparison already showed.

// correct
if (a.compareTo(b) < 0) { ... }

// fragile
if (a.compareTo(b) == -1) { ... }

Lesson 6b's "Alan Turing".compareTo("Ada Lovelace") returned 8, not 1 — because String's version returns a character difference. A caller testing == 1 would work for Card and fail for String, which is why the contract is about the sign only.

41. Comparing objects with < and >

Trap

Card a = new Card(3, 0);
Card b = new Card(2, 1);

if (a < b) { ... }          // does not compile
if (a > b) { ... }          // does not compile

if (a.compareTo(b) < 0) {
    System.out.println("a is lower");
} else if (a.compareTo(b) > 0) {
    System.out.println("a is higher");
} else {
    System.out.println("equivalent");
}

42. Totally, partially or unordered?

Definition probe

Can any two values be compared?

43. Compare against zero

Fill the middle

Test whether a comes before b.

44. Could compareTo rank Aces high?

Counterexample

The encoding puts Ace at 1, the lowest rank.

45. Cards are immutable

Section

Section 12.5

46. Getters, and the decision not to write setters

Concept

The instance variables of Card are private, so they cannot be accessed from other classes. We provide getters to let other classes read the rank and suit — and then face a design decision about setters.

public int getRank() {
    return this.rank;
}

public int getSuit() {
    return this.suit;
}

Whether or not to provide setters is a design decision. If we did, cards would be mutable, so you could transform one card into another — that is probably not a feature we want, and in general mutable objects are more error-prone.

47. Two ways to make a class immutable

Picture it

Omitting setters is enough. Declaring the instance variables final is enough and enforced.

That is easy enough, but it is not foolproof, because a fool might come along later and add a modifier. Declaring the instance variables final prevents that possibility — and the fool in question is usually you, six months later.

48. Making Card immutable

Worked example

One keyword per instance variable, and the class becomes impossible to modify rather than merely unmodified.

public class Card {
    private final int rank;
    private final int suit;

    public Card(int rank, int suit) {
        this.rank = rank;      // legal - initialising a final variable
        this.suit = suit;
    }

    public void setRank(int rank) {
        this.rank = rank;      // compile error
    }
}

49. What does final on an instance variable prevent?

Prediction

It permits one assignment.

private final int rank;

public Card(int rank) {
    this.rank = rank;        // ?
}

public void setRank(int rank) {
    this.rank = rank;        // ?
}

50. Why immutable is the safer default

Concept

Chapter 10 argued that neither design is always better. For a Card, the arguments point one way.

The last row matters for Chapter 13: a Deck will shuffle by rearranging references, and the Cards themselves never change. That is only safe because Card is immutable — which is Lesson 9a's argument that immutability makes sharing free, now being relied on rather than merely described.

51. Relying on the absence of setters

Trap

public class Card {
    private int rank;         // not final
    private int suit;

    // no setters... today
}

// six months later, someone adds:
public void setRank(int rank) {
    this.rank = rank;         // compiles fine
}

public class Card {
    private final int rank;
    private final int suit;
    ...
}
// now the setter cannot be written at all

52. Which design for which class?

Definition probe

Chapter 10's question, applied to specific types.

53. Make the class immutable

Fill the middle

Prevent any future method from modifying the data.

54. Why does immutability matter more in a team?

Real world

Alone, you could just remember not to add a setter.

55. Three kinds of variable, complete

Comparison

Chapter 12 adds the last one. Fill the blanks.

The bottom row explains an error you have probably hit: main is static, so it cannot use instance variables — but it can use class variables freely, which is why Card.SUITS works anywhere.

56. The pattern to carry away

Pattern

Encoding a set of values as integers, then decoding for display, is a technique you will reuse well beyond cards.

// 1. encode: choose a mapping, and write it down
//    Clubs -> 0, Diamonds -> 1, Hearts -> 2, Spades -> 3
private final int suit;

// 2. decode: an array whose INDEX ORDER is the mapping
public static final String[] SUITS =
    {"Clubs", "Diamonds", "Hearts", "Spades"};

// 3. display: use the value as an index
public String toString() {
    return RANKS[this.rank] + " of " + SUITS[this.suit];
}

// 4. compare: the integers make an order possible
public int compareTo(Card that) { ... }

• static means shared; final means constant — two separate decisions.
• compareTo returns a sign, and callers compare it against zero.
• A partially ordered type needs the class to impose an order.
• final instance variables make immutability enforced rather than conventional.

57. Check: class variables

Check

Work it out before you click.

public class Card {
    public static final String[] SUITS = {"Clubs", ...};
    private int suit;
}
// 52 Card objects are created

58. Check: compareTo

Check

Work it out before you click.

// suit is compared first
Card a = new Card(13, 0);   // King of Clubs
Card b = new Card(2, 1);    // 2 of Diamonds
a.compareTo(b)

59. Check: final

Check

Work it out before you click.

public class Card {
    private final int rank;

    public Card(int rank) {
        this.rank = rank;
    }

    public void setRank(int r) {
        this.rank = r;
    }
}

60. Encoding is everywhere

Real world

Mapping a set of things onto integers so they can be compared, indexed and stored compactly is one of the oldest techniques in programming.

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, out loud.

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

Five sections that design a class carefully — and every decision in it is one Chapters 13 and 14 will rely on.

• Encoding means defining a mapping between numbers and things; the mapping is design, not code.
• Integers were chosen over Strings because comparison is the hard operation and integers make it easy.
• An array of Strings decodes an integer back into a word, using the value as an index.
• A class variable is declared static and has one copy shared by all instances, allocated when the program begins.
• static means shared and final means constant — two separate considerations.
• final on an array reference does not protect the elements.
• compareTo returns a sign, and a partially ordered type needs the class to impose an order.
• Omitting setters makes a class immutable; final instance variables make it enforced.