C# IEquatable<T>: Fast, Type-Safe Equality for Your Types

Equals(object) forces a struct into a box just to compare it. IEquatable<T> exists so it never has to.

You just wrote a correct Equals(object?)/GetHashCode() pair in the previous lesson, and it works perfectly. So why does .NET also define a whole separate interface, IEquatable<T>, that seemingly does the exact same job? The answer only becomes visible when the type doing the comparing is a struct:

That comparison is correct, but it's quietly wasteful — Equals(object?) takes an object parameter, and passing a struct where an object is expected means boxing it, exactly the heap-allocation overhead you learned to watch for back in the value-vs-reference-types lesson. Every single equality check on this struct pays that cost, even though nothing about comparing two coordinates should ever need the heap.

In this lesson, you'll learn why IEquatable<T> exists specifically to eliminate that boxing, how to implement it correctly alongside Equals and GetHashCode, and why it matters most for value types — though classes benefit too, for different reasons.

What Is It?

The Simple Explanation

IEquatable<T> is a second, more specific way for a type to say "here's how you compare me to another instance of my own exact type" — instead of the general-purpose Equals(object?), which has to accept literally anything and figure out the type at runtime, IEquatable<T>.Equals(T) already knows exactly what type it's comparing against, checked at compile time.

The Technical Definition

IEquatable<T> is a generic interface with exactly one member:

This is an overload, not an override — a type implementing IEquatable<T> ends up with two Equals methods side by side: the inherited Equals(object?) (which you should still override, for consistency, exactly as in the previous lesson) and this new, strongly-typed Equals(T?). The compiler picks whichever overload matches the compile-time type of the argument, and for a struct, calling the T-typed overload never requires boxing either argument.

Why Does It Exist?

The Problem

Recall from the value-vs-reference-types lesson: a value type gets boxed the moment it's assigned to something typed as object, and every boxing operation is a heap allocation with real, measurable cost. object.Equals(object?)'s parameter is literally typed object — so calling it on a struct boxes both the receiver and the argument, every single time:

Now imagine this comparison running inside a tight loop — deduplicating a million Coordinate values, say, or as the comparison callback for a HashSet<Coordinate>. A million unnecessary boxing allocations is a real, avoidable performance cost, and it's entirely a side effect of Equals(object?)'s parameter type — nothing about comparing two coordinates fundamentally requires the heap.

The Solution

IEquatable<T>.Equals(T? other) takes its parameter as the concrete type T — for Coordinate, that's Equals(Coordinate other) — so neither the receiver nor the argument ever needs to become an object. .NET's own generic collections (List<T>.Contains, Dictionary<TKey,TValue>, HashSet<T>, and more) all check whether T implements IEquatable<T> and, if so, call the strongly-typed overload automatically — meaning implementing this one extra method can make an entire codebase's worth of comparisons on your type boxing-free, without changing any calling code.

Big Picture

How It Works

public struct Coordinate : IEquatable<Coordinate>
{
    public double Latitude, Longitude;

    public bool Equals(Coordinate other) =>
        Latitude == other.Latitude && Longitude == other.Longitude;
    // ...
}

public override bool Equals(object? obj) =>
    obj is Coordinate other && Equals(other);   // reuses the strongly-typed version above

public override int GetHashCode() => HashCode.Combine(Latitude, Longitude);

Simple Example

Code → Meaning → Result:

• a.Equals(b) resolves to the strongly-typed overload at compile time, since both sides are known to be Coordinate — no boxing happens.
• Explicitly boxing b and calling Equals(object?) still works correctly — it just delegates straight back to the strongly-typed version, so the logic is never duplicated.
• HashSet<Coordinate> automatically uses the strongly-typed Equals internally — the boxing-free path is the default once you've implemented the interface, with zero changes to how you use the collection.

Real-World Example

A location-tracking feature that deduplicates thousands of GPS coordinate readings per second is a realistic scenario where the boxing avoided by IEquatable<T> genuinely matters — not as a micro-optimization nobody would notice, but as the difference between a responsive real-time feature and one that stutters under GC pressure from constant boxing.

Every call to _seenLocations.Add(reading) internally compares the incoming GpsReading against existing entries — without IEquatable<GpsReading>, each of those comparisons would box the struct being compared. At thousands of readings per second, that's thousands of unnecessary heap allocations per second, adding real, avoidable pressure on the garbage collector. Implementing the interface removes that cost entirely.

Analogy

Under the Hood

Common Confusion

1. Equals(T) and Equals(object?) are two separate methods, not one overriding the other

A common mistake is thinking IEquatable<T>.Equals(T) "replaces" object.Equals(object?) the way an override would. It doesn't — they coexist as two overloads of the same method name, and the compiler picks whichever one matches the compile-time type of the argument. That's exactly why you still need to override Equals(object?) separately, and why delegating it to Equals(T) is the recommended pattern.

2. Implementing IEquatable<T> alone doesn't fix hash-based collections — GetHashCode still has to be right

It's tempting to think adding IEquatable<T> is a complete equality solution on its own. It isn't — the contract from the previous lesson (equal objects must produce equal hash codes) still applies in full, regardless of how many Equals overloads exist. All three methods — Equals(T), Equals(object?), and GetHashCode() — need to agree with each other.

3. The boxing benefit is specifically a value-type story — don't expect the same magnitude of gain on a class

As covered in "Under the Hood," classes never boxed in the first place, so IEquatable<T>'s benefit there is a smaller type-check/cast savings, not a heap-allocation savings. The dramatic performance story — avoiding a heap allocation on every comparison — is specific to structs, which is exactly why this lesson leaned on Coordinate and GpsReading as its examples.

Common Mistakes

Mistake 1 — Implementing Equals(T) and Equals(object?) with inconsistent logic

Wrong — the two methods disagree, which is confusing and can produce different results depending on which overload happens to be called:

Correct — always have Equals(object?) delegate to Equals(T), so there's exactly one source of truth:

Mistake 2 — Implementing IEquatable<T> but forgetting GetHashCode

This reintroduces exactly the contract violation from the previous lesson — a struct can be "equal" via IEquatable<T> while still hashing inconsistently, breaking HashSet<T> and dictionary lookups in the same silent way. All three methods — Equals(T), Equals(object?), GetHashCode() — are a package deal; implement all three together.

Mistake 3 — Assuming IEquatable<T> matters equally for every type

Chasing this optimization on a reference type that's rarely compared, or on a struct that's rarely used in hot paths or large collections — added complexity for negligible real benefit. Prioritize implementing it on struct types that will realistically be compared frequently, especially inside collections or tight loops, exactly like the GPS example.

When Should I Use It?

Mental Model

Key Takeaway

Check Your Understanding

You've learned why IEquatable<T> exists specifically to avoid boxing. Let's check your understanding.

You now understand equality, hashing, ordering, and how to avoid boxing on comparisons — the full toolkit for well-behaved custom types. Next: the capstone of this module — building your own collection type from scratch with IEnumerable<T> and yield return, tying generics, iteration, and equality together.