Passing a `Card` object to an instance method of the `Card` class

A very common confusion for beginning Java programmers
- I found from past experiences that some CS170 students get confused when an instance method contains an object variable
- In this webpage, we will define an instance method in the Card class that compare if 2 cards are equal
  We will also see an example on how such an instance method is used.

Comparing if 2 cards are equal

Problem description:

Write an instance method to compare if 2 card objects are equal
The method equals must return true if the 2 cards are equal
The method equals must return false otherwise.
When are 2 cards equal to each other:

Note:

I will use a stripped down version of the Card class to keep the focus on the equals() method.
I will omit the suit, suitStr, rank, and rankStr, methods...

How would you use the equals method

Let us first find out how to use the equals() method:

equals is an instance method.

So we need to use an implicit parameter to invoke the equals method.

Example:

public class TestCard2 { public static void main(String[] args) { Card a = new Card ( Card.CLUB, 1 ); ... a.equals( ... ) .... } }

The parameter a is one of the tow cards in the comparison operation.

equals compares 2 (two) cards.

So we need to pass another Card typed parameter the equals method.

Example:

public class TestCard2 { public static void main(String[] args) { Card a = new Card ( Card.CLUB, 1 ); Card b = new Card ( Card.SPADE, 1 ); ... a.equals( b ) .... } }

The equals method returns true or false.
So we need to use the result as a boolean typed expression --- for example, in an if-else statement.
Example:

public class TestCard2 { public static void main(String[] args) { Card a = new Card ( Card.CLUB, 1 ); Card b = new Card ( Card.SPADE, 1 ); if ( a.equals( b ) System.out.println(a + " is equal to " + b); else System.out.println(a + " is NOT equal to " + b); } }

Java program that uses the equals() method:

public class TestCard2 { public static void main(String[] args) { Card a = new Card ( Card.CLUB , 1 ); Card b = new Card ( Card.SPADE, 1 ); Card c = new Card ( Card.CLUB , 1 ); if ( a.equals(b) ) System.out.println(a + " is equal to " + b); else System.out.println(a + " is NOT equal to " + b); if ( a.equals(c) ) System.out.println(a + " is equal to " + b); else System.out.println(a + " is NOT equal to " + b); } }

Defining the equals() method

Initial attempt

public class Card { public static final int SPADE = 4; public static final int HEART = 3; public static final int CLUB = 2; public static final int DIAMOND = 1; private static final String[] Suit = { "*", "d", "c", "h", "s"}; private static final String[] Rank = { "*", "*", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K", "A"}; private byte cardSuit; private byte cardRank; public Card( int suit, int rank ) { if ( rank == 1 ) cardRank = 14; // Give Ace the rank 14 else cardRank = (byte) rank; cardSuit = (byte) suit; } /* ---------------------------------------------------- equal(): Compare if 2 cards are equal ---------------------------------------------------- */ public boolean equals( Card x ) { ... I see ONLY ONE Card object: x ... Where is the other Card object that I need to ... compare with ???? } public String toString() { return ( Rank[ cardRank ] + Suit[ cardSuit ] ); } }

Some cs170 students are puzzled by the fact that they only see one Card parameter variable

and they need to compare two (2) cards !!!!

Solution: the other card is the implicit parameter this !!!

public class Card { public static final int SPADE = 4; public static final int HEART = 3; public static final int CLUB = 2; public static final int DIAMOND = 1; private static final String[] Suit = { "*", "d", "c", "h", "s"}; private static final String[] Rank = { "*", "*", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K", "A"}; private byte cardSuit; private byte cardRank; public Card( int suit, int rank ) { if ( rank == 1 ) cardRank = 14; // Give Ace the rank 14 else cardRank = (byte) rank; cardSuit = (byte) suit; } /* ---------------------------------------------------- equal(): Compare if 2 cards are equal You only see ONE card object: x Students often forget that INSTANCE methods ALWAYS have an IMPLICIT parameter "this" --- that's the other card !!! ---------------------------------------------------- */ public boolean equals( Card x ) { if ( this.cardSuit == x.cardSuit && this.cardRank == x.cardRank ) return ( true ); else return ( false ); } public String toString() { return ( Rank[ cardRank ] + Suit[ cardSuit ] ); } }

Output:

Ac is NOT equal to As Ac is equal to As

Example Program: (Demo above code)
- The Cards.java Prog file with the equals() method: click here
- The TestCards2.java Prog file: click here
How to run the program:

What happens behind the scenes in the invocation: a.equals(b)

This is what happens behind the scenes:

First, two Card objects a and b are created:
The method call "a.equals(b)" passes:
- a as the implicit parameter this
- b as the explicit parameter x

Using the short hand notation in the equals() method

Consider the equals() method:

public boolean equals( Card x ) { if ( this.cardSuit == x.cardSuit && this.cardRank == x.cardRank ) return ( true ); else return ( false ); }

Local and parameter variables defined in equals():

Parameter variables: x
Local variables: none

Conclussion:

There is no name conflict with the instance variable name cardSuit
There is no name conflict with the instance variable name cardRank

So we can use the short hand notation and drop the this. object variable without any problems:

public boolean equals( Card x ) { if ( cardSuit == x.cardSuit && cardRank == x.cardRank ) return ( true ); else return ( false ); }

Try it yourself:

Passing a Card object to an instance method of the Card class

Passing a `Card` object to an instance method of the `Card` class