Java equals, hashCode, and toString

The concept

By default, two objects are equal only if they are the same object. A class that represents a value, such as a point, should override equals so that two points with the same coordinates count as equal. It must then also override hashCode so that equal objects have the same hash code, otherwise hash-based collections such as HashSet and HashMap behave incorrectly.

The contract is: equal objects have equal hash codes, equals is reflexive, symmetric, and transitive, and the result does not change while the object is unchanged. Objects.equals and Objects.hash make a correct implementation short. toString should return a readable description, because it is used when an object is printed or logged.

Code example

import java.util.*;

class Main {
  static class Point {
    private final int x;
    private final int y;

    Point(int x, int y) {
      this.x = x;
      this.y = y;
    }

    @Override
    public boolean equals(Object other) {
      if (this == other) {
        return true;
      }
      if (!(other instanceof Point)) {
        return false;
      }
      Point p = (Point) other;
      return x == p.x && y == p.y;
    }

    @Override
    public int hashCode() {
      return Objects.hash(x, y);
    }

    @Override
    public String toString() {
      return "(" + x + "," + y + ")";
    }
  }

  public static void main(String[] args) {
    Point a = new Point(1, 2);
    Point b = new Point(1, 2);
    System.out.println((a == b) + " " + a.equals(b));

    Set<Point> seen = new HashSet<>();
    seen.add(a);
    seen.add(b);
    seen.add(new Point(3, 4));
    System.out.println(seen.size() + " " + seen.contains(new Point(3, 4)));
    System.out.println(a + " " + (a.hashCode() == b.hashCode()));
  }
}

false true
2 true
(1,2) true

Follow the code

Open the walkthrough to inspect the example one step at a time.

—

—

false true

false true

false true
2 true

false true
2 true
(1,2) true

Behind the scenes

Cost and common mistakes

equals and hashCode are O(1) here; set operations are O(1) on average.

• Overriding equals without hashCode breaks HashSet and HashMap: equal points could land in different buckets.
• Do not use mutable fields in equals and hashCode of keys. Changing a key inside a set makes it unfindable.
• The parameter of equals must be Object. A method equals(Point) is an overload, not an override.

Try it yourself

What would the set size be without the hashCode override?

Further reading

• Dev.java: learn Java (external)
• Java SE 17 API documentation (external)