In .NET 4.0, What is the default implementation of Equals for value types?

Question

The two documentation pages seem to contradict on this topic:

• ValueType.Equals Method says "The default implementation of the Equals method uses reflection to compare the corresponding fields of obj and this instance."
• Object.Equals Method (Object) says "The default implementation of Equals supports reference equality for reference types, and bitwise equality for value types."

So is it bitwise equality or reflection?

I took a glimpse at the source code of ValueType and found a comment saying

// if there are no GC references in this object we can avoid reflection

// and do a fast memcmp

Can someone clarify what "GC reference" means? I guess it's a field having a reference type but I'm not sure.

If I create a struct which only has value type fields, will the instances of it be always compared the fast way?

UPDATE: The documentation for.Net 4.5 has been significantly improved: it is free from the mentioned contradiction and now gives a better understanding how the default value type equality checking works.

Answer 1

System.ValueType.Equals is special. It does the following steps, in order, until it gets some result:

1. If the obj comparing to is 'null', it returns false.
2. If the this and obj arguments are different types, it returns false.
3. If the type is "blittable" it compares the memory images. If they are identical, it returns true.
4. Finally, it uses reflection to call Equals the paired-up instance fields for each value. If any of those fields are not equal, it returns false. Otherwise it returns true. Note that it never calls the base method, Object.Equals.

Because it uses reflection to compare the fields, you should always override Equals on any ValueType you create. Reflection is slow.

When it's a "GCReference", or a field in the struct that is a reference type, it winds up using reflection on each field to do the comparison. It has to do this, because the struct actually has a pointer to the reference type's location on the heap.

If there is no reference type used in the struct, and they are the same type, the fields are guaranteed to be in the same order, and be the same size in memory, so it can just compare the bare memory.

For a struct with only value types for fields, i.e. a struct with only one int field, no reflection is done during a comparison. None of the fields reference anything on the heap, so there is no GCReference or GCHandle. Furthermore, any instance of this structure will have the same in-memory layout of the fields (with a few minor exceptions), so the CLR team can do a direct memory comparison (memcmp), which is much faster than the other option.

So yes, if you only have value types in your structure, it will do the faster memcmp, instead of the reflection comparison, but you may not want to do that. Keep reading.

This does not mean you should use the default Equals implementation. In fact, do not do that. Stop it. It's doing bit comparisons, which are not always accurate. What is that you say? Let me show you:

private struct MyThing
{
    public float MyFloat;
}

private static void Main(string[] args)
{
    MyThing f, s;
    f.MyFloat = 0.0f;
    s.MyFloat = -0.0f;

    Console.WriteLine(f.Equals(s));  // prints False
    Console.WriteLine(0.0f == -0.0f); // prints True
}

The numbers are equal mathematically, but they are not equal in their binary representation. So, I will stress it again, do not rely on the default implementation of ValueType.Equals