C# / .NET Compendium PLEN
.NET / C# / Algorithms, data structures

IEquatable<T>

What it is

IEquatable<T> is a generic interface from System that defines a single method:

public interface IEquatable<T>
{
    bool Equals(T other);
}

By implementing it we say: "my type knows how to compare itself with a specific, known type T — without casting and without boxing".

Why Equals(object) alone is not enough

Every type in .NET inherits Equals(object obj) from System.Object. The problem is that:

  • the parameter is of type object, so it has to be cast ((Order)obj) and checked with is/as — extra overhead,
  • for structs (struct) calling Equals(object) requires boxing the value (because object is a reference), which is expensive and generates garbage for the GC,
  • the default ValueType.Equals implementation for structs uses reflection, which is slow.

IEquatable<T> solves this by providing a strongly typed, direct comparison method — no casting, no boxing, no reflection.

A full example

public class Order : IEquatable<Order>
{
    public Guid Id { get; }
    public decimal Amount { get; }

    public Order(Guid id, decimal amount)
    {
        Id = id;
        Amount = amount;
    }

    // Strongly typed comparison - this is the heart of IEquatable<T>
    public bool Equals(Order? other)
    {
        if (other is null) return false;
        if (ReferenceEquals(this, other)) return true;

        return Id == other.Id && Amount == other.Amount;
    }

    // Equals(object) delegujemy do Equals(Order)
    public override bool Equals(object? obj) => Equals(obj as Order);

    public override int GetHashCode() => HashCode.Combine(Id, Amount);

    public static bool operator ==(Order? left, Order? right)
    {
        if (left is null) return right is null;
        return left.Equals(right);
    }

    public static bool operator !=(Order? left, Order? right) => !(left == right);
}

The rule you have to follow: if you override Equals, you must also override GetHashCode() — two "equal" objects must have the same hash code, otherwise Dictionary/HashSet will fall apart.

Where it matters in practice

  • List<T>.Contains, IndexOf, Remove — if T implements IEquatable<T>, the collection uses it directly. If not, it falls back to Equals(object) (slower, with casting).
  • Dictionary<TKey, TValue> and HashSet<T> — the default EqualityComparer<T>.Default checks at runtime whether T implements IEquatable<T>, and if so, uses it. For structs this is a huge performance difference (no boxing on every check).
  • Structs (struct) — this is where the gain is the biggest. A struct without IEquatable<T> gets boxed on every comparison in a collection. With IEquatable<T> — zero allocations.
public readonly struct Point : IEquatable<Point>
{
    public int X { get; }
    public int Y { get; }

    public Point(int x, int y) { X = x; Y = y; }

    public bool Equals(Point other) => X == other.X && Y == other.Y;
    public override bool Equals(object? obj) => obj is Point p && Equals(p);
    public override int GetHashCode() => HashCode.Combine(X, Y);
}

Without IEquatable<Point>, every list.Contains(point) would box Point to object under the hood — with the interface we avoid this completely.

What about record?

record types automatically generate a value-based (member-wise) comparison implementation, including Equals(T), Equals(object), GetHashCode() and the ==/!= operators — which is exactly what we wrote by hand above. This is one of the main reasons record is convenient for DTOs/value objects — you don't have to write this boilerplate yourself.

public record OrderDto(Guid Id, decimal Amount);
// IEquatable<OrderDto> + Equals + GetHashCode + == + != - wszystko za darmo

Summary

Aspect Equals(object) IEquatable<T>.Equals(T)
Typing weak (object) strong (T)
Boxing for a struct yes no
Performance in collections slower (cast + possible boxing) faster (direct call)
GetHashCode also required yes yes
Generated automatically by record yes yes
Buy me a coffee