Comparing Objects with compareTo

Suppose you store playing cards in a collection and then ask the collection whether a particular card is present. Methods such as contains and remove perform this search for you: they look through the collection for an item that matches the one you supplied. The result depends entirely on what the word matches means. If that meaning is wrong, the collection will appear to lose cards, fail to find cards that are plainly there, or behave in ways that seem random.

A very common first instinct is to compare two objects with the == operator and assume that a true result means the objects hold the same data. That instinct is a misconception. The == operator asks a narrower question: do the two expressions refer to the same object in memory? Two separate objects can hold identical data and still fail the == test, because == does not look inside them. This article follows the meaning of equality for objects, because that meaning is what a collection relies on when it searches, and it then extends the same idea to ordering with compareTo.

It helps to separate two questions that look alike. The first question is identity: are these two references pointing at one and the same object? The second question is equality: do these two objects represent the same value? Identity is a fact about where the objects live. Equality is a fact about what they mean. A pair of references can answer yes to both questions, no to identity but yes to equality, or no to both. Only the first kind of answer comes automatically from the == operator.

Read the diagram as two situations. In the upper pair, x and y are two names for one object, so == returns true and the values agree trivially. In the lower pair, p and q lead to two different objects that both hold a suit of 2 and a value of 7. Their contents match, which is an equality question, but the == operator still reports false, because it only checks whether both references lead to the same object. The == operator answers the identity question automatically; answering the equality question requires code that you write.

Consider a Card class that stores a suit as a number from 0 to 3 and a value as a number from 1 to 13. Two cards should count as equal when both fields match. The overriding method first converts the incoming object to a Card so that its fields can be read. If that conversion succeeds, it compares the suit and the value. If it fails, it returns false, because the object cannot possibly be an equal card.

Trace a matching pair. The conversion succeeds, both the suit and the value agree, and the method returns true. Now trace a mismatched pair with the same suit but different values. The conversion succeeds, the suit comparison passes, the value comparison fails, and the method returns false. For an object that is null, the conversion path fails and the method returns false without crashing. The source names two situations: a null reference leads to a NullPointerException and an object of some other type leads to a ClassCastException. In both situations the method catches the exception and returns false, because a null reference or a foreign object cannot be equal to a card.

The debugging question is not whether equals() exists, but where in its logic a result departs from what you expected. A correct method can still produce a wrong answer if the comparison reads the wrong fields or stops at the wrong point. Follow the comparison step by step, note which value is read from which object, and check the answer at each branch. Then locate the exact line where the observed outcome first differs from the intended one.

Numbers and strings have an obvious order, but a program cannot sort a collection of arbitrary objects until it knows how to decide that one object comes before another. Sorting means arranging items in ascending order according to some criterion. For custom objects there is no built-in notion of that criterion, so something must be defined for comparing them before a sort can proceed.

The before column is the original list and the after column is the same objects in ascending order by last name. The sort cannot place Hopper before or after Lovelace without a rule that answers which of two objects comes first. That rule is the comparison. Comparable and Comparator, covered below, are two ways of supplying it.

The Comparable interface is a parameterized interface, written Comparable<T>, that expresses the ability to be compared to an object of type T. It defines exactly one method, compareTo, which takes an object of type T as its parameter. Calling obj1.compareTo(obj2) asks obj1 to report where it stands relative to obj2. Only the sign of the result matters: a negative result means obj1 comes before obj2, a positive result means obj1 comes after obj2, and zero means the two are the same for that comparison.

The source develops a class called FullName, which holds a first name and a last name, both required to be non-null. To make FullName objects sortable, the class declares that it implements Comparable<FullName> and defines compareTo so that the last name is the primary key. Only when two last names match does the first name decide the order. The method returns -1 or 1 when the last names differ, and it returns the first-name comparison result when they match. Both forms satisfy the convention because only the sign matters.

Comparable puts the comparison inside the class. A Comparator takes a different approach: it is a separate object whose job is to compare two objects of some type T. The object must implement Comparator<T>, and the interface defines one method, compare(T obj1, T obj2). Its return value follows the same sign convention as compareTo. Comparators are useful in two situations: comparing objects whose class does not implement Comparable, such as a class you cannot modify, and defining several different orderings over the same collection of objects. Because Comparator is a functional interface, comparators are often written as lambda expressions.

The source notes that a Comparator does not have to agree with equals. A comparator that looks only at the zip code reports zero for two different addresses that share a zip code, even though they are not equal in every field. That is a deliberate choice for the ordering, not a mistake. It also means that two objects can be sorted as tied while still being unequal, which is worth remembering when an ordering seems to merge items you expected to keep apart.

Use Comparable when the class has one obvious natural order that belongs to the class itself. Use Comparator when the class cannot be changed, or when the same objects need more than one ordering. When an order looks wrong after sorting, trace the comparison rule that the sort actually uses: check whether it reads the primary key first, whether it returns zero where you expected a difference, and whether it is the rule you intended to supply.