equals()
========
Every class has an equals() method.  If you don't define one explictly, you
inherit Object.equals(), for which "r1.equals(r2)" returns the same boolean
value as "r1 == r2", where r1 and r2 are references.  However, many classes
override equals() to compare the _content_ of two objects.

Integer (in the java.lang library) is such a class; it stores one private int.
Two distinct Integer objects are equals() if they contain the same int.
In the following example, "i1 == i2" is false, but "i1.equals(i2)" is true.
"i2 == i3" and "i2.equals(i3)" are both true.

           ---    -------            ---    -------    ---
        i1 |.+--->|  7  |         i2 |.+--->|  7  |<---+.| i3
           ---    -------            ---    -------    ---

IMPORTANT:  r1.equals(r2) throws a run-time exception if r1 is null.

There are at least four different degrees of equality.
(1)  Reference equality, ==.  (The default inherited from the Object class.)
(2)  Shallow structural equality:  two objects are "equals" if all their fields
     are ==.  For example, two SLists whose "size" fields are equal and whose
     "head" fields point to the same SListNode.
(3)  Deep structural equality:  two objects are "equals" if all their fields
     are "equals".  For example, two SLists that represent the same sequence of
     items (though the SListNodes may be different).
(4)  Logical equality.  Two examples:
     (a)  Two "Set" objects are "equals" if they contain the same elements,
          even if the underlying lists store the elements in different orders.
     (b)  The Fractions 1/3 and 2/6 are "equals", even though their numerators
          and denominators are all different.

The equals() method for a particular class may test any of these four levels of
equality, depending on what seems appropriate.  Let's write an equals() method
for SLists that tests for deep structural equality.  The following method
returns true only if the two lists represent identical sequences of items.

  public class SList {
    public boolean equals(Object other) {
      if (!(other instanceof SList)) {           // Reject non-SLists.
        return false;
      }

      SList o = (SList) other;
      if (size != o.size) {
        return false;
      }

      SListNode n1 = head;
      SListNode n2 = o.head;
      while (n1 != null) {
        if (!n1.item.equals(n2.item)) {          // Deep equality of the items.
          return false;
        }
        n1 = n1.next;
        n2 = n2.next;
      }
      return true;
    }
  }

Note that this implementation may fail if the SList invariants have been
corrupted.  (A wrong "size" field or a loop in an SList can make it fail.)

IMPORTANT:  Overriding DOESN'T WORK if we change the signature of the original
method, even just to change a parameter to a subclass.  In the Object class,
the signature is equals(Object), so in the code above, we must declare "other"
to be an Object too.  If we declare "other" to be an SList, the equals() method
will compile but it will NOT override.  That means the code

  Object s = new SList();
  s.equals(s);

will call Object.equals(), not SList.equals().  Dynamic method lookup won't
care that s is an SList, because the equals() method above is not eligible to
override Object.equals().

Therefore, if you want to override a method, make sure the signature is EXACTLY
the same.