Question

I have a custom generic data structure that includes a Find method:

public bool Find(TValue value, IEqualityComparer<TValue> comparer)
{
    foreach (var x in items)
    {
        if (comparer.Equals(value, x))
            return true;
    }
    return false;
}

I got a report recently from a client who said that it causes his equality comparer to throw NullReferenceException if value is null or if one of the items in the collection is null.

My initial response was that his IEqualityComparer<T>.Equals implementation was in error because it doesn’t deal gracefully with null values. But I haven’t been able to find any documentation to explicitly back me up. I have some evidence to indicate that I’m right, but nothing explicit.

First, it seems silly that I’d have change that simple call to comparer.Equals to:

if (x == null)
{
    if (value == null)
        return true;
}
else if (value != null && comparer.Equals(value, x))
    return true;

Second, the documentation for Object.Equals says, among other things:

• x.Equals(null) returns false.
• Implementations of Equals must not throw exceptions.

That, to me, is strong evidence that IEqualityComparer<T>.Equals should gracefully handle null parameters.

Other evidence is that the documentation for IComparer.Compare says:

Comparing null with any reference type is allowed and does not
generate an exception. A null reference is considered to be less than
any reference that is not null.

One would expect IEqualityComparer<T>.Equals to act similarly. It’s amusing to note, though, that the example given on that page will throw NullReferenceException if either parameter is null.

I’ve been through the documentation for Object.Equals, IEquatable<T>, IEqualityComparer<T>, and IEqualityComparer, and countless blog posts, articles, and SO questions. Nothing gives any specific guidelines about how to handle null parameters.

Do such guidelines exist? If not, what do the gurus recommend, and why?

Answer 1

The closest method in the .NET framework itself after which all IEqualityComparer.Equals methods should be modeled is the static Object.Equals(object,object) method. According to the documentation, this method handles nulls gracefully. I think that this provides enough indication on the intent of the .NET designers: IEqualityComparer.Equals should handle nulls as well, and it should handle them in a similar way (i.e. treating two nulls as equal to each other).