Mono Class Library: System.Object Overview | Members

System.Object.Equals Method

Determines whether the specified object is equal to the current instance. [Edit]

public virtual bool Equals (object obj)

Parameters

obj
The object to compare with the current instance. [Edit]

Returns

true if obj is equal to the current instance; otherwise, false. [Edit]

Remarks

Operation

The statements listed below are required to be true for all implementations of the object.Equals(object) method. In the list, x, y, and z represent non-null object references.

  • x.Equals(x) returns true.
  • x.Equals(y) returns the same value as y.Equals(x).
  • If (x.Equals(y) && y.Equals(z)) returns true, then x.Equals(z) returns true.
  • Successive invocations of x.Equals(y) return the same value as long as the objects referenced by x and y are not modified.
  • x.Equals(null) returns false for non-null x.

See object.GetHashCode for additional required behaviors pertaining to the object.Equals(object) method.

Note: Implementations of object.Equals(object) should not throw exceptions.

The object.Equals(object) method tests for referential equality , which means that object.Equals(object) returns true if the specified instance of Object and the current instance are the same instance; otherwise, it returns false .

Note:

An implementation of the object.Equals(object) method is shown in the following C# code:

public virtual bool Equals(Object obj) {
return this == obj;
}
Note to Inheritors

For some kinds of objects, it is desirable to have object.Equals(object) test for value equality instead of referential equality. Such implementations of Equals return true if the two objects have the same "value", even if they are not the same instance. The definition of what constitutes an object's "value" is up to the implementer of the type, but it is typically some or all of the data stored in the instance variables of the object. For example, the value of a string is based on the characters of the string; the Equals method of the string class returns true for any two string instances that contain exactly the same characters in the same order.

When the Equals method of a base class provides value equality, an override of Equals in a class derived from that base class should invoke the inherited implementation of Equals .

All implementations of object.GetHashCode are required to ensure that for any two object references x and y, if x.Equals(y) == true, then x.GetHashCode() == y.GetHashCode().

If your programming language supports operator overloading, and if you choose to overload the equality operator for a given type, that type should override the Equals method. Such implementations of the Equals method should return the same results as the equality operator. Following this guideline will help ensure that class library code using Equals (such as ArrayList and Hashtable ) behaves in a manner that is consistent with the way the equality operator is used by application code.

If you are implementing a value type, you should follow these guidelines:

  • Consider overriding Equals to gain increased performance over that provided by the default implementation of Equals on ValueType.
  • If you override Equals and the language supports operator overloading, you should overload the equality operator for your value type.

For reference types, the guidelines are as follows:

  • Consider overriding Equals on a reference type if the semantics of the type are based on the fact that the type represents some value(s). For example, reference types such as Point and BigNumber should override Equals.
  • Most reference types should not overload the equality operator, even if they override Equals . However, if you are implementing a reference type that is intended to have value semantics, such as a complex number type, you should override the equality operator.

If you implement IComparable on a given type, you should override Equals on that type.

Usage
The object.Equals(object) method is called by methods in collections classes that perform search operations, including the Array.IndexOf(Array, object) method and the ArrayList.Contains(object) method.

[Edit]

Example

Example 1:

The following example contains two calls to the default implementation of object.Equals(object) .

C# Example
using System;
class MyClass {
   static void Main() {
      Object obj1 = new Object();
      Object obj2 = new Object();
      Console.WriteLine(obj1.Equals(obj2));
      obj1 = obj2; 
      Console.WriteLine(obj1.Equals(obj2)); 
   }
}

The output is

False
True

Example 2:

The following example shows a Point class that overrides the object.Equals(object) method to provide value equality and a class Point3D, which is derived from Point . Because Point's override of object.Equals(object) is the first in the inheritance chain to introduce value equality, the Equals method of the base class (which is inherited from object and checks for referential equality) is not invoked. However, Point3D.Equals invokes Point.Equals because Point implements Equals in a manner that provides value equality.

C# Example
using System;
public class Point: object {
 int x, y;
 public override bool Equals(Object obj) {
 //Check for null and compare run-time types.
 if (obj == null || GetType() != obj.GetType()) return false;
 Point p = (Point)obj;
 return (x == p.x) && (y == p.y);
 }
 public override int GetHashCode() {
 return x ^ y;
 }
}

class Point3D: Point {
 int z;
 public override bool Equals(Object obj) {
 return base.Equals(obj) && z == ((Point3D)obj).z;
 }
 public override int GetHashCode() {
 return base.GetHashCode() ^ z;
 }
}

The Point.Equals method checks that the obj argument is non-null and that it references an instance of the same type as this object. If either of those checks fail, the method returns false. The object.Equals(object) method uses object.GetType to determine whether the run-time types of the two objects are identical. (Note that typeof is not used here because it returns the static type.) If instead the method had used a check of the form obj is Point , the check would return true in cases where obj is an instance of a subclass of Point , even though obj and the current instance are not of the same runtime type. Having verified that both objects are of the same type, the method casts obj to type Point and returns the result of comparing the instance variables of the two objects.

In Point3D.Equals , the inherited Equals method is invoked before anything else is done; the inherited Equals method checks to see that obj is non-null, that obj is an instance of the same class as this object, and that the inherited instance variables match. Only when the inherited Equals returns true does the method compare the instance variables introduced in the subclass. Specifically, the cast to Point3D is not executed unless obj has been determined to be of type Point3D or a subclass of Point3D .

Example 3:

In the previous example, operator == (the equality operator) is used to compare the individual instance variables. In some cases, it is appropriate to use the object.Equals(object) method to compare instance variables in an Equals implementation, as shown in the following example:

C# Example
using System;
class Rectangle {
 Point a, b;
 public override bool Equals(Object obj) {
 if (obj == null || GetType() != obj.GetType()) return false;
 Rectangle r = (Rectangle)obj;
 //Use Equals to compare instance variables
 return a.Equals(r.a) && b.Equals(r.b);
 }
 public override int GetHashCode() {
 return a.GetHashCode() ^ b.GetHashCode();
 }
}

Example 4:

In some languages, such as C#, operator overloading is supported. When a type overloads operator ==, it should also override the object.Equals(object) method to provide the same functionality. This is typically accomplished by writing the Equals method in terms of the overloaded operator ==. For example:

C# Example
using System;
public struct Complex {
 double re, im;
 public override bool Equals(Object obj) {
 return obj is Complex && this == (Complex)obj;
 }
 public override int GetHashCode() {
 return re.GetHashCode() ^ im.GetHashCode();
 }
 public static bool operator ==(Complex x, Complex y) {
 return x.re == y.re && x.im == y.im;
 }
 public static bool operator !=(Complex x, Complex y) {
 return !(x == y);
 }
}

Because Complex is a C# struct (a value type), it is known that there will be no subclasses of Complex . Therefore, the object.Equals(object) method need not compare the GetType() results for each object, but can instead use the is operator to check the type of the obj parameter.

Requirements

Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0
This documentation is part of the Mono Project.