Object.Equals Method (Object)
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Updated: October 2010
Namespace: System
Assembly: mscorlib (in mscorlib.dll)
Syntax
'Declaration
Public Overridable Function Equals ( _
obj As Object _
) As Boolean
public virtual bool Equals(
Object obj
)
Parameters
- obj
Type: System.Object
The Object to compare with the current Object.
Return Value
Type: System.Boolean
true if the specified Object is equal to the current Object; otherwise, false.
Remarks
The default implementation of Equals supports reference equality for reference types, and bitwise equality for value types. Reference equality means the object references that are compared refer to the same object. Bitwise equality means the objects that are compared have the same binary representation.
Note that a derived type might override the Equals method to implement value equality. Value equality means the compared objects have the same value even though they have different binary representations. For example, consider two Decimal objects that represent the numbers 1.10 and 1.1000. The Decimal objects do not have bitwise equality because they have different binary representations to account for the different number of trailing zeroes. However, the objects have value equality because the numbers 1.10 and 1.1000 are considered equal for comparison purposes since the trailing zeroes are insignificant.
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 nulla 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.
If (x.Equals(y) && y.Equals(z)) returns true, then 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(nulla null reference (Nothing in Visual Basic)) returns false.
See GetHashCode for additional required behaviors pertaining to the Equals method.
Implementations of Equals must not throw exceptions.
For some kinds of objects, it is desirable to have Equals 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 type's implementer decides what constitutes an object's "value", but it is typically some or all 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.
Types that implement IComparable must override Equals.
Types that override Equals must also override GetHashCode.
If your programming language supports operator overloading and if you choose to overload the equality operator for a given type, that type must override the Equals method. Such implementations of the Equals method must return the same results as the equality operator. Following this guideline will help ensure that class library code using Equals behaves in a manner that is consistent with the way the equality operator is used by application code.
The following guidelines are for implementing a value type:
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.
The following guidelines are for implementing a reference 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.
Examples
The following code example compares the current instance with another object.
Public Class Example
Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
Dim Obj1 As New Object()
Dim Obj2 As New Object()
outputBlock.Text &= Obj1.Equals(Obj2) & vbCrLf '===> false
Obj2 = Obj1
outputBlock.Text &= Obj1.Equals(Obj2) & vbCrLf '===> true
End Sub
End Class
using System;
public class Example
{
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
Object Obj1 = new Object();
Object Obj2 = new Object();
outputBlock.Text += Obj1.Equals(Obj2) + "\n"; //===> false
Obj2 = Obj1;
outputBlock.Text += Obj1.Equals(Obj2) + "\n"; //===> true
}
}
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.
Class Point
Inherits Object
Protected x, y As Integer
Public Sub New()
Me.x = 0
Me.y = 0
End Sub 'New
Public Sub New(ByVal X As Integer, ByVal Y As Integer)
Me.x = X
Me.y = Y
End Sub 'New
Public Overrides Function Equals(ByVal obj As Object) As Boolean
'Check for null and compare run-time types.
If obj Is Nothing OrElse Not [GetType]().Equals(obj.GetType()) Then
Return False
End If
Dim p As Point = CType(obj, Point)
Return x = p.x AndAlso y = p.y
End Function 'Equals
Public Overrides Function GetHashCode() As Integer
Return x ^ y
End Function 'GetHashCode
End Class 'Point
Class Point3D
Inherits Point
Private z As Integer
Public Sub New(ByVal X As Integer, ByVal Y As Integer, ByVal Z As Integer)
Me.x = X
Me.y = Y
Me.z = Z
End Sub 'New
Public Overrides Function Equals(ByVal obj As Object) As Boolean
Return MyBase.Equals(obj) AndAlso z = CType(obj, Point3D).z
End Function 'Equals
Public Overrides Function GetHashCode() As Integer
Return MyBase.GetHashCode() ^ z
End Function 'GetHashCode
End Class 'Point3D
Class Example
Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
Dim point2D As New Point(5, 5)
Dim point3Da As New Point3D(5, 5, 2)
Dim point3Db As New Point3D(5, 5, 2)
If Not point2D.Equals(point3Da) Then
outputBlock.Text &= "point2D does not equal point3Da." & vbCrLf
End If
If Not point3Db.Equals(point2D) Then
outputBlock.Text += String.Format("Likewise, point3Db does not equal point2D.") & vbCrLf
End If
If point3Da.Equals(point3Db) Then
outputBlock.Text += String.Format("However, point3Da equals point3Db.") & vbCrLf
End If
End Sub 'Main
End Class '[MyClass]
' ----------------------------------
' Output should be:
'
' point2D does not equal point3Da.
' Likewise, point3Db does not equal point2D.
' However, point3Da equals point3Db.
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;
}
}
class Example
{
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
Point point2D = new Point(5, 5);
Point3D point3Da = new Point3D(5, 5, 2);
Point3D point3Db = new Point3D(5, 5, 2);
if (!point2D.Equals(point3Da))
{
outputBlock.Text += "point2D does not equal point3Da." + "\n";
}
if (!point3Db.Equals(point2D))
{
outputBlock.Text += String.Format("Likewise, point3Db does not equal point2D.") + "\n";
}
if (point3Da.Equals(point3Db))
{
outputBlock.Text += String.Format("However, point3Da equals point3Db.") + "\n";
}
}
}
// ----------------------------------
// Output should be:
//
// point2D does not equal point3Da.
// Likewise, point3Db does not equal point2D.
// However, point3Da equals point3Db.
The Point.Equals method checks that the obj argument is not nulla 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 nulla 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, 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 example.
Class Rectangle
Private a, b As Point
Public Sub New(ByVal upLeftX As Integer, ByVal upLeftY As Integer, _
ByVal downRightX As Integer, ByVal downRightY As Integer)
Me.a = New Point(upLeftX, upLeftY)
Me.b = New Point(downRightX, downRightY)
End Sub 'New
Public Overrides Function Equals(ByVal obj As [Object]) As Boolean
' Performs an equality check on two rectangles (Point object pairs).
If obj Is Nothing OrElse Not [GetType]().Equals(obj.GetType()) Then
Return False
End If
Dim r As Rectangle = CType(obj, Rectangle)
'Uses Equals to compare variables.
Return a.Equals(r.a) AndAlso b.Equals(r.b)
End Function 'Equals
Public Overrides Function GetHashCode() As Integer
Return a.GetHashCode() ^ b.GetHashCode()
End Function 'GetHashCode
End Class 'Rectangle
' Class Point added for clean compile
Class Point
Private x As Integer
Private y As Integer
Public Sub New(ByVal X As Integer, ByVal Y As Integer)
Me.x = X
Me.y = Y
End Sub 'New
Public Overrides Function Equals(ByVal obj As [Object]) As Boolean
' Performs an equality check on two points (integer pairs).
If obj Is Nothing OrElse Not [GetType]().Equals(obj.GetType()) Then
Return False
End If
Dim p As Point = CType(obj, Point)
Return x = p.x AndAlso y = p.y
End Function 'Equals
Public Overrides Function GetHashCode() As Integer
Return x.GetHashCode() ^ y.GetHashCode()
End Function 'GetHashCode
End Class 'Point
Class Example
Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
Dim r1 As New Rectangle(0, 0, 100, 200)
Dim r2 As New Rectangle(0, 0, 100, 200)
Dim r3 As New Rectangle(0, 0, 150, 200)
If r1.Equals(r2) Then
outputBlock.Text &= "Rectangle r1 equals rectangle r2!" & vbCrLf
End If
If Not r2.Equals(r3) Then
outputBlock.Text &= "But rectangle r2 does not equal rectangle r3." & vbCrLf
End If
End Sub 'Main
End Class '[MyClass]
' ------------------------------
' Output should be:
' Rectangle r1 equals rectangle r2!
' But rectangle r2 does not equal rectangle r3.
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();
}
}
// Class Point added for clean compile
class Point
{
private int x;
private int y;
public Point(int X, int Y)
{
this.x = X;
this.y = Y;
}
public override bool Equals(Object obj)
{
// Performs an equality check on two points (integer pairs).
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.GetHashCode() ^ y.GetHashCode();
}
}
class Example
{
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
Rectangle r1 = new Rectangle(0, 0, 100, 200);
Rectangle r2 = new Rectangle(0, 0, 100, 200);
Rectangle r3 = new Rectangle(0, 0, 150, 200);
if (r1.Equals(r2))
{
outputBlock.Text += "Rectangle r1 equals rectangle r2!" + "\n";
}
if (!r2.Equals(r3))
{
outputBlock.Text += "But rectangle r2 does not equal rectangle r3." + "\n";
}
}
}
// ------------------------------
// Output should be:
// Rectangle r1 equals rectangle r2!
// But rectangle r2 does not equal rectangle r3.
In some languages, such as C# and Visual Basic, operator overloading is supported. When a type overloads the equality 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 equality operator, as in the following example.
Public Structure Complex
Public re, im As Double
Public Overrides Function Equals(ByVal obj As [Object]) As Boolean
Return TypeOf obj Is Complex AndAlso [GetType]().Equals(CType(obj, Complex))
End Function
Public Overrides Function GetHashCode() As Integer
Return re.GetHashCode() ^ im.GetHashCode()
End Function
Public Shared Operator = (x As Complex, y As Complex) As Boolean
Return x.re = y.re AndAlso x.im = y.im
End Operator
Public Shared Operator <> (x As Complex, y As Complex) As Boolean
Return Not (x = y)
End Operator
End Structure
Class Example
Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
Dim cmplx1, cmplx2 As Complex
cmplx1.re = 4.0
cmplx1.im = 1.0
cmplx2.re = 2.0
cmplx2.im = 1.0
If cmplx1 <> cmplx2 Then
outputBlock.Text &= "The two objects are not equal." & vbCrLf
End If
If Not cmplx1.Equals(cmplx2) Then
outputBlock.Text &= "The two objects are not equal." & vbCrLf
End If
cmplx2.re = 4.0
If cmplx1.Equals(cmplx2) Then
outputBlock.Text &= "The two objects are now equal!" & vbCrLf
End If
If cmplx1 = cmplx2 Then
outputBlock.Text &= "The two objects are now equal!" & vbCrLf
End If
End Sub
End Class
' The example displays the following output:
' The two objects are not equal.
' The two objects are not equal.
' The two objects are now equal!
' The two objects are now equal!
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);
}
}
class Example
{
public static void Demo(System.Windows.Controls.TextBlock outputBlock)
{
Complex cmplx1, cmplx2;
cmplx1.re = 4.0;
cmplx1.im = 1.0;
cmplx2.re = 2.0;
cmplx2.im = 1.0;
if (cmplx1 != cmplx2)
Console.WriteLine("The two objects are not equal.");
if (! cmplx1.Equals(cmplx2))
Console.WriteLine("The two objects are not equal.");
cmplx2.re = 4.0;
if (cmplx1 == cmplx2)
Console.WriteLine("The two objects are now equal!");
if (cmplx1.Equals(cmplx2))
Console.WriteLine("The two objects are now equal!");
}
}
// The example displays the following output:
// The two objects are not equal.
// The two objects are not equal.
// The two objects are now equal!
// The two objects are now equal!
Because Complex is 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.
Version Information
Silverlight
Supported in: 5, 4, 3
Silverlight for Windows Phone
Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0
XNA Framework
Supported in: Xbox 360, Windows Phone OS 7.0
Platforms
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.
See Also
Reference
Change History
Date |
History |
Reason |
|---|---|---|
October 2010 |
Revised the last example. |
Customer feedback. |