equals, hashCode, toString

the picture

you know how two new Point(1, 2) aren't equals until you say so? Object can't know what "the same" means for your class, so it plays it safe: same object or nothing.

think of a library. equals is "is this the same book?" (same title and author, not the same physical copy). hashCode is the shelf number: the catalogue says Moby-Dick lives on shelf 12, so that's the only shelf anyone checks. if two copies of the same book get different shelf numbers, the librarian looks on the wrong shelf and swears you don't have it.

the equals contract

overriding equals is signing a contract with every collection in the JDK. five promises:

// CIString: a case-insensitive string
public boolean equals(Object o) {
    if (o instanceof CIString c)
        return s.equalsIgnoreCase(c.s);
    if (o instanceof String str)       // one-way
        return s.equalsIgnoreCase(str);
    return false;
}

the good version, written out:

final class Point {
    private final int x, y;
 
    Point(int x, int y) { this.x = x; this.y = y; }
 
    @Override
    public boolean equals(Object o) {
        return o instanceof Point p    // false for null and other types
            && x == p.x && y == p.y;   // the fields that define "same value"
    }
 
    @Override
    public int hashCode() {
        return Objects.hash(x, y);     // the same fields, nothing else
    }
 
    @Override
    public String toString() {
        return "Point(" + x + ", " + y + ")";
    }
}

or let the compiler do it. record Point(int x, int y) {} generates exactly this equals, a matching hashCode and a readable toString. see records.

hashCode: the half people forget

a HashSet is a HashMap underneath: an array of buckets. to find an object it computes hashCode(), mixes the bits, and checks one bucket. only inside that bucket does it call equals. so if two equal objects produce different hash codes, they land in different buckets, and equals never even gets asked.

class Point {
    final int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
 
    @Override
    public boolean equals(Object o) {
        return o instanceof Point p && x == p.x && y == p.y;
    }
    // no hashCode
}
 
Set<Point> set = new HashSet<>();
set.add(new Point(1, 2));
IO.println(set.contains(new Point(1, 2)));
set.add(new Point(1, 2));
IO.println(set.size());

import java.util.*;
 
class Point {
    final int x, y;
 
    Point(int x, int y) {
        this.x = x;
        this.y = y;
    }
 
    @Override
    public boolean equals(Object o) {
        return o instanceof Point p && x == p.x && y == p.y;
    }
    // no hashCode: inherited from Object
}
 
public class Main {
    public static void main(String[] args) {
        Set<Point> set = new HashSet<>();
        set.add(new Point(1, 2));
        System.out.println(set.contains(new Point(1, 2)));
        set.add(new Point(1, 2));
        System.out.println(set.size());
    }
}

false
2

the rules for hashCode, all following from "the set looks in one bucket":

• equal objects must have equal hash codes. (the one you can't break.)
• unequal objects may share a hash code. that's a collision, it's legal, it's just slower.
• it must stay the same while the object is in a collection, so build it from the same fields equals uses, ideally final ones.

toString: what Object@hex means

Object.toString() is getClass().getName() + "@" + Integer.toHexString(hashCode()). that hex is just the hash code. so if you override hashCode but not toString, the hex changes to your hash:

import java.util.*;
 
class Point {
    final int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
 
    @Override
    public boolean equals(Object o) {
        return o instanceof Point p && x == p.x && y == p.y;
    }
 
    @Override
    public int hashCode() {
        return Objects.hash(x, y);   // 31 * (31 + 1) + 2 = 994 = 0x3e2
    }
}
 
public class Ts {
    public static void main(String[] args) {
        Point p = new Point(1, 2);
        System.out.println(p);
        System.out.println(Integer.toHexString(p.hashCode()));
        System.out.println(new HashSet<>(List.of(p)).contains(new Point(1, 2)));
    }
}

Point@3e2
3e2
true

it is not a memory address. it's a hash, and with the default hashCode it's a random-ish number the JVM generates once and stores in the object's header (that's what the mark word's hash bits are for, see classes and objects). override toString on anything you'll ever log: it costs nothing and saves hours.

import java.math.BigDecimal;
import java.util.*;
 
public class Bd {
    public static void main(String[] args) {
        var a = new BigDecimal("1.0");
        var b = new BigDecimal("1.00");
        System.out.println(a.equals(b) + " " + a.compareTo(b));
        System.out.println(new HashSet<>(List.of(a, b)).size() + " " + new TreeSet<>(List.of(a, b)).size());
    }
}

false 0
2 1