Object.Equals Method (Object)

public virtual bool Equals (
	Object obj
)

public boolean Equals (
	Object obj
)

public function Equals (
	obj : Object
) : boolean

Parameters

obj

The Object to compare with the current Object.

Return Value

The default implementation of Equals supports reference equality only, but derived classes can override this method to support value equality.

For reference types, equality is defined as object equality; that is, whether the references refer to the same object. For value types, equality is defined as bitwise equality. The ValueType class supports value types.

Notes to Implementers This method can be overridden by a derived class. For example, many of the base data types return true if both objects represent the same value; otherwise, false. This method only compares primitives and objects. It must be overridden to compare more complex structures, such as arrays of objects. The following statements must be true for all implementations of the Equals method. In the list, x, y, and z represent object references that are not a null reference (Nothing in Visual Basic).

• x.Equals(x) returns true, except in cases that involve floating-point types. See IEC 60559:1989, Binary Floating-point Arithmetic for Microprocessor Systems.

• x.Equals(y) returns the same value as y.Equals(x).

• x.Equals(y) returns true if both x and y are NaN.

• (x.Equals(y) && y.Equals(z)) returns true if and only if x.Equals(z) returns true.

• Successive calls to x.Equals(y) return the same value as long as the objects referenced by x and y are not modified.

• x.Equals(a null reference (Nothing in Visual Basic)) returns false.

• 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 must overload the equality operator for your value type.

• 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).

• Most reference types must 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 must override the equality operator.

The following code example compares the current instance with another object.

using System;

public class Sample {
    void Method() {
    Object Obj1 = new Object();
    Object Obj2 = new Object();
    Console.WriteLine(Obj1.Equals(Obj2)); //===> false
    Obj2 = Obj1;
    Console.WriteLine(Obj1.Equals(Obj2)); //===> true
    }
}

import System.*;

public class Sample
{
    void Method()
    {
        Object obj1 = new Object();
        Object obj2 = new Object();
        Console.WriteLine(obj1.Equals(obj2)); //===> false
        obj2 = obj1;
        Console.WriteLine(obj1.Equals(obj2)); //===> true
    } //Method
} //Sample

The following example shows a Point class that overrides the Equals method to provide value equality and a class Point3D, which is derived from Point. Because Point 's override of Equals 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.

using System;

class Point: Object {
   protected int x, y;

   public Point() {
     this.x = 0;
     this.y = 0;
   }

   public Point(int X, int Y) {
      this.x = X;
      this.y = 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 Point3D(int X, int Y, int Z) {
      this.x = X;
      this.y = Y;
      this.z = 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 not a null reference (Nothing in Visual Basic) and that it references an instance of the same type as this object. If either of those checks fail, the method returns false.

The Equals method uses 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 the method used a check of the form obj is Point, the check would return true in cases where obj is an instance of a derived class 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 not a null reference (Nothing in Visual Basic), 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 derived class. Specifically, the cast to Point3D is not executed unless obj has been determined to be of type Point3D or a derived class of Point3D.

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 Equals method to compare instance variables in an Equals implementation, as shown in the following code example.

using System;

class Rectangle {
   Point a, b;

   public Rectangle(int upLeftX, int upLeftY, int downRightX, int downRightY) {
      this.a = new Point(upLeftX, upLeftY);
      this.b = new Point(downRightX, downRightY);
   }

   public override bool Equals(Object obj) {
     // Performs an equality check on two rectangles (Point object pairs).
      if (obj == null || GetType() != obj.GetType()) return false;
      Rectangle r = (Rectangle)obj;
      //Uses Equals to compare variables.
      return a.Equals(r.a) && b.Equals(r.b);
   }

   public override int GetHashCode() {
      return a.GetHashCode() ^ b.GetHashCode();
   }

}

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

using System;

public struct Complex {
   public 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 cannot be derived from; therefore, the Equals 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.

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

.NET Compact Framework