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 withis/as— extra overhead, - for structs (
struct) callingEquals(object)requires boxing the value (becauseobjectis a reference), which is expensive and generates garbage for the GC, - the default
ValueType.Equalsimplementation 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— ifTimplementsIEquatable<T>, the collection uses it directly. If not, it falls back toEquals(object)(slower, with casting).Dictionary<TKey, TValue>andHashSet<T>— the defaultEqualityComparer<T>.Defaultchecks at runtime whetherTimplementsIEquatable<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 withoutIEquatable<T>gets boxed on every comparison in a collection. WithIEquatable<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 |