Common Object Operations in .NET

Object Equality and Identity

The System.Object type offers a virtual method, named Equals, whose purpose is to return true if two objects have the same "value." The .NET Framework Class Library (FCL) includes many methods, such as System.Array's IndexOf method and System.Collections.ArrayList's Contains method, which internally call Equals. Because Equals is defined by Object, and because every type is ultimately derived from Object, every instance of every type offers the Equals method. For types that don't explicitly override Equals, the implementation provided by Object (or the nearest base class that overrides Equals) is inherited. The following code shows how System.Object's Equals method is essentially implemented:

class Object {
  public virtual Boolean Equals(Object obj) {

   // If both references point to the same 
   // object, they must be equal.
   if (this == obj) return(true);

   // Assume that the objects are not equal.
   return(false);
  }
  §
}

As you can see, this method takes the simplest approach possible: If the two references being compared point to the same object, true is returned; in any other case, false is returned. If you define your own types and you want to compare their fields for equality, Object's default implementation won't be sufficient for you; you must override Equals and provide your own implementation.

When you implement your own Equals method, you must ensure that it adheres to the four properties of equality:

• Equals must be reflexive; that is, x.Equals(x) must return true.

• Equals must be symmetric; that is, x.Equals(y) must return the same value as y.Equals(x).

• Equals must be transitive; that is, if x.Equals(y) returns true and y.Equals(z) returns true, then x.Equals(z) must also return true.

• Equals must be consistent. Provided that there are no changes in the two values being compared, Equals should consistently return true or false.

If your implementation of Equals fails to adhere to all these rules, your application will behave in strange and unpredictable ways.

Unfortunately, implementing your own version of Equals isn't as easy and straightforward as you might expect. You must do a number of operations correctly, and, depending on the type you're defining, the operations are slightly different. Fortunately, there are only three different ways to implement Equals. Let's look at each pattern individually.

Implementing Equals for a Reference Type Whose Base Classes Don't Override Object's Equals

The following code shows how to implement Equals for a type that directly inherits Object's Equals implementation:

// This is a reference type (because of 'class').
class MyRefType : BaseType {
  RefType refobj;  // This field is a reference type.
  ValType valobj;  // This field is a value type.

  public override Boolean Equals(Object obj) {
   // Because 'this' isn't null, if obj is null, 
   // then the objects can't be equal.
   if (obj == null) return false;

   // If the objects are of different types, they can't be equal.
   if (this.GetType() != obj.GetType()) return false;

   // Cast obj to this type to access fields. NOTE: This cast can't
   // fail because you know that objects are of the same type.
   MyRefType other = (MyRefType) obj;

   // To compare reference fields, do this:
   if (!Object.Equals(refobj, other.refobj)) return false;

   // To compare value fields, do this: 
   if (!valobj.Equals(other.valobj)) return false;

   return true;  // Objects are equal.
  }

  // Optional overloads of the == and != operators
  public static Boolean operator==(MyRefType o1, MyRefType o2) {
   if (o1 == null) return false;
   return o1.Equals(o2);
  }

  public static Boolean operator!=(MyRefType o1, MyRefType o2) {
   return !(o1 == o2);
  }
}

This version of Equals starts out by comparing obj against null. If the object being compared is not null, then the types of the two objects are compared. If the objects are of different types, then they can't be equal. If both objects are the same type, then you cast obj to MyRefType, which can't possibly throw an exception because you know that both objects are of the same type. Finally, the fields in both objects are compared, and true is returned if all fields are equal.

You must be very careful when comparing the individual fields. The preceding code shows two different ways to compare the fields based on what types of fields you're using.

• Comparing reference type fields—To compare reference type fields, you should call Object's static Equals method. Object's static Equals method is just a little helper method that returns true if two reference objects are equal. Here's how Object's static Equals method is implemented internally:

  public static Boolean Equals(Object objA, Object objB) {
    // If objA and objB refer to the same object, return true.
    if (objA == objB) return true;
  
    // If objA or objB is null, they can't be equal, so return false.
    if ((objA == null) || (objB == null)) return false;
  
    // Ask objA if objB is equal to it, and return the result.
    return objA.Equals(objB);
  }

  You use this method to compare reference type fields because it's legal for them to have a value of null. Certainly, calling refobj.Equals(other.refobj) will throw a NullReferenceException if refobj is null. Object's static Equals helper method performs the proper checks against null for you.

• Comparing value type fields—To compare value type fields, you should call the field type's Equals method to have it compare the two fields. You shouldn't call Object's static Equals method because value types can never be null and calling the static Equals method would box both value type objects.

Implementing Equals for a Reference Type When One or More of Its Base Classes Overrides Object's Equals

The following code shows how to implement Equals for a type that inherits an implementation of Equals other than the one Object provides:

// This is a reference type (because of 'class').
class MyRefType : BaseType {
  RefType refobj;  // This field is a reference type.
  ValType valobj;  // This field is a value type.

  public override Boolean Equals(Object obj) {
   // Let the base type compare its fields.
   if (!base.Equals(obj)) return false;

   // All the code from here down is identical to
   // that shown in the previous version.

   // Because 'this' isn't null, if obj is null, 
   // then the objects can't be equal.
   // NOTE: This line can be deleted if you trust that
   // the base type implemented Equals correctly.
   if (obj == null) return false;

   // If the objects are of different types, they can't be equal.
   // NOTE: This line can be deleted if you trust that
   // the base type implemented Equals correctly.
   if (this.GetType() != obj.GetType()) return false;

   // Cast obj to this type to access fields. NOTE: This cast
   // can't fail because you know that objects are of the same type.
   MyRefType other = (MyRefType) obj;

   // To compare reference fields, do this:
   if (!Object.Equals(refobj, other.refobj)) return false;

   // To compare value fields, do this:
   if (!valobj.Equals(other.valobj)) return false;

   return true;  // Objects are equal.
  }

  // Optional overloads of the == and != operators
  public static Boolean operator==(MyRefType o1, MyRefType o2) {
   if (o1 == null) return false;
   return o1.Equals(o2);
  }

  public static Boolean operator!=(MyRefType o1, MyRefType o2) {
   return !(o1 == o2);
  }
}

This code is practically identical to the code shown in the previous section. The only difference is that this version allows its base type to compare its fields, too. If the base type doesn't think the objects are equal, then they can't be equal.

It is very important that you not call base.Equals if this would result in calling the Equals method provided by System.Object. The reason is that Object's Equals method returns true only if the references point to the same object. If the references don't point to the same object, then false will be returned and your Equals method will always return false!

Certainly, if you're defining a type that is directly derived from Object, you should implement Equals as shown in the previous section. If you're defining a type that isn't directly derived from Object, you must first determine if that type (or any of its base types, except Object) provides an implementation of Equals. If any of the base types provides an implementation of Equals, then call base.Equals as shown in this section.

Implementing Equals for a Value Type

All value types are derived from System.ValueType. ValueType overrides the implementation of Equals offered by System.Object. Internally, System.ValueType's Equals method uses reflection to get the type's instance fields and compares the fields of both objects to see if they have equal values. This process is very slow, but it's a reasonably good default implementation that all value types will inherit. However, it does mean that reference types inherit an implementation of Equals that is really identity and that value types inherit an implementation of Equals that is value equality.

For value types that don't explicitly override Equals, the implementation provided by ValueType is inherited. The following code shows how System.-ValueType's Equals method is essentially implemented:

class ValueType {
  public override Boolean Equals(Object obj) {

   // Because 'this' isn't null, if obj is null, 
   // then the objects can't be equal.
   if (obj == null) return false;

   // Get the type of 'this' object.
   Type thisType = this.GetType();

   // If 'this' and 'obj' are different types, they can't be equal.
   if (thisType != obj.GetType()) return false;

   // Get the set of public and private instance
   // fields associated with this type.
   FieldInfo[] fields = thisType.GetFields(BindingFlags.Public |
     BindingFlags.NonPublic | BindingFlags.Instance);

   // Compare each instance field for equality. 
   for (Int32 i = 0; i < fields.Length; i++) {

     // Get the value of the field from both objects.
     Object thisValue = fields[i].GetValue(this);
     Object thatValue = fields[i].GetValue(obj);

     // If the values aren't equal, the objects aren't equal.
     if (!Object.Equals(thisValue, thatValue)) return false;
   }

   // All the field values are equal, and the objects are equal.
   return true;
  }
  §
}

Even though ValueType offers a pretty good implementation for Equals that would work for most value types that you define, you should still provide your own implementation of Equals. The reason is that your implementation will perform significantly faster and will be able to avoid extra boxing operations.

The following code shows how to implement Equals for a value type:

// This is a value type (because of 'struct').
struct MyValType {
  RefType refobj;  // This field is a reference type.
  ValType valobj;  // This field is a value type.

  public override Boolean Equals(Object obj) {
   // If obj is not your type, then the objects can't be equal.
   if (!(obj is MyValType)) return false;

   // Call the type-safe overload of Equals to do the work.
   return this.Equals((MyValType) obj);

  }

  // Implement a strongly typed version of Equals.
  public Boolean Equals(MyValType obj) {
   // To compare reference fields, do this:
   if (!Object.Equals(this.refobj, obj.refobj)) return false;

   // To compare value fields, do this:
   if (!this.valobj.Equals(obj.valobj)) return false;

   return true;  // Objects are equal.
  }

  // Optionally overload operator==
  public static Boolean operator==(MyValType v1, MyValType v2) {
   return (v1.Equals(v2));
  }

  // Optionally overload operator!=
  public static Boolean operator!=(MyValType v1, MyValType v2) {
   return !(v1 == v2);
  }
}

For value types, the type should define a strongly typed version of Equals. This version takes the defining type as a parameter, giving you type safety and avoiding extra boxing operations. You should also provide strongly typed operator overloads for the == and != operators. The following code demonstrates how to test two value types for equality:

MyValType v1, v2;

// The following line calls the strongly typed version of
// Equals (no boxing occurs).
if (v1.Equals(v2)) { ... }

// The following line calls the version of
// Equals that takes an object (4 is boxed).
if (v1.Equals(4)) { ... }

// The following doesn't compile because operator== 
// doesn't take a MyValType and an Int32.
if (v1 == 4) { ... }

// The following compiles, and no boxing occurs.
if (v1 == v2) { ... }

Inside the strongly typed Equals method, the code compares the fields in exactly the same way that you'd compare them for reference types. Keep in mind that the code doesn't do any casting, doesn't compare the two instances to see if they're the same type, and doesn't call the base type's Equals method. These operations aren't necessary because the method's parameter already ensures that the instances are of the same type. Also, because all value types are immediately derived from System.ValueType, you know that your base type has no fields of its own that need to be compared.

You'll notice in the Equals method that takes an Object that I used the is operator to check the type of obj. I used is instead of GetType because calling GetType on an instance of a value type requires that the instance be boxed.

Summary of Implementing Equals and the ==/!= Operators

In this section, I summarize how to implement equality for your own types:

• Compiler primitive types—Your compiler will provide implementations of the == and != operators for types that it considers primitives. For example, the C# compiler knows how to compare Object, Boolean, Char, Int16, Uint16, Int32, Uint32, Int64, Uint64, Single, Double, Decimal, and so on for equality. In addition, these types provide implementations of Equals, so you can call this method as well as use operators.

• Reference types—For reference types that you define, override the Equals method and, in the method, do all the work necessary to compare object states and return. If your type doesn't inherit Object's Equals method, call the base type's Equals method. If you want, overload the == and != operators and have them call the Equals method to do the actual work of comparing the fields.

• Value types—For your value types, define a type-safe version of Equals that does all the work necessary to compare object states and return. Implement the type unsafe version of Equals by having it call the type-safe Equals internally. You also should provide overloads of the == and != operators that call the type-safe Equals method internally.

Identity

The purpose of a type's Equals method is to compare two instances of the type and return true if the instances have equivalent states or values. However, it's sometimes useful to see whether two references refer to the same, identical object. To do this, System.Object offers a static method called ReferenceEquals, which is implemented as follows:

class Object {
  public static Boolean ReferenceEquals(Object objA, Object objB) {
   return (objA == objB);
  }
}

As you can plainly see, ReferenceEquals simply uses the == operator to compare the two references. This works because of rules contained within the C# compiler. When the C# compiler sees that two references of type Object are being compared using the == operator, the compiler generates IL code that checks whether the two variables contain the same reference.

If you're writing C# code, you could use the == operator instead of calling Object's ReferenceEquals method, if you prefer. However, you must be very careful. The == operator is guaranteed to check identity only if the variables on both sides of the == operator are of the System.Object type. If a variable isn't of the Object type and if that variable's type has overloaded the == operator, the C# compiler will produce code to call the overloaded operator's method instead. So, for clarity and to ensure that your code always works as expected, don't use the == operator to check for identity; instead, you should use Object's static ReferenceEquals method. Here's some code demonstrating how to use ReferenceEquals:

static void Main() {
  // Construct a reference type object.
  RefType r1 = new RefType();

  // Make another variable point to the reference object.
  RefType r2 = r1;

  // Do r1 and r2 point to the same object?
  Console.WriteLine(Object.ReferenceEquals(r1, r2)); // "True"

  // Construct another reference type object.
  r2 = new RefType();

  // Do r1 and r2 point to the same object?
  Console.WriteLine(Object.ReferenceEquals(r1, r2)); // "False"

  // Create an instance of a value type.
  Int32 x = 5;

  // Do x and x point to the same object?
  Console.WriteLine(Object.ReferenceEquals(x, x));  // "False"
  // "False" is displayed because x is boxed twice
  // into two different objects.
}