Bibliothèque de classes .NET Framework
Object.Equals, méthode (Object)

Détermine si l'Object spécifié est égal à l'Object en cours.

Espace de noms : System
Assembly : mscorlib (dans mscorlib.dll)

Syntaxe

Visual Basic (Déclaration)
Public Overridable Function Equals ( _
    obj As Object _
) As Boolean
Visual Basic (Utilisation)
Dim instance As Object
Dim obj As Object
Dim returnValue As Boolean

returnValue = instance.Equals(obj)
C#
public virtual bool Equals (
    Object obj
)
C++
public:
virtual bool Equals (
    Object^ obj
)
J#
public boolean Equals (
    Object obj
)
JScript
public function Equals (
    obj : Object
) : boolean

Paramètres

obj

Object à comparer au Object en cours.

Valeur de retour

true si l'Object spécifié est égal à l'Object en cours ; sinon, false.
Notes

L'implémentation de Equals par défaut prend en charge l'égalité des références uniquement, mais les classes dérivées peuvent substituer cette méthode pour prendre en charge l'égalité des valeurs.

Pour les types référence, l'égalité est définie comme une égalité d'objets, c'est-à-dire si les références renvoient ou non au même objet. Pour les types valeur, l'égalité est définie comme une égalité au niveau du bit. La classe ValueType prend en charge les types valeur.

Remarques à l'attention des implémenteurs Cette méthode peut être substituée par une classe dérivée. Par exemple, de nombreux types de données de base retournent true si les deux objets représentent la même valeur ; sinon, false. Cette méthode ne compare que des primitives et des objets. Elle doit être substituée pour comparer des structures plus complexes, telles que des tableaux d'objets. Les instructions suivantes doivent avoir la valeur true pour toutes les implémentations de la méthode Equals. Dans la liste, x, y et z représentent des références d'objet non référence Null (Nothing en Visual Basic).

  • x.Equals(x) retourne true, sauf dans des scénarios qui impliquent des types virgule flottante. Consultez IEC 60559:1989, Binary Floating-point Arithmetic for Microprocessor Systems.

  • x.Equals(y) retourne la même valeur que y.Equals(x).

  • x.Equals(y) retourne true si x et y sont NaN.

  • (x.Equals(y) && y.Equals(z)) retourne true si et seulement si x.Equals(z) retourne true.

  • Les appels successifs à x.Equals(y) retournent la même valeur aussi longtemps que les objets référencés par x et y ne sont pas modifiés.

  • x.Equals(référence Null (Nothing en Visual Basic)) retourne false.

Pour les comportements supplémentaires nécessaires propres à la méthode Equals, consultez GetHashCode. Les implémentations de Equals ne doivent pas lever d'exception. Pour certains types d'objets, il est souhaitable que Equals teste l'égalité des valeurs plutôt que l'égalité des références. De telles implémentations de Equals retournent true si les deux objets possèdent la même « valeur », même s'il ne s'agit pas de la même instance. L'implémenteur du type décide ce qui constitue la « valeur » d'un objet, mais il s'agit généralement d'une partie ou de la totalité des données stockées dans les variables d'instance de l'objet. Par exemple, la valeur de String se base sur les caractères de la chaîne. La méthode Equals de la classe String retourne true lorsque deux instances de chaîne contiennent exactement les mêmes caractères dans le même ordre. Les types qui implémentent IComparable doivent substituer Equals. Les types qui substituent Equals doivent également substituer GetHashCode ; sinon, il se peut que Hashtable ne fonctionne pas correctement. Si votre langage de programmation prend en charge la surcharge d'opérateur et si vous choisissez de surcharger l'opérateur d'égalité pour un type donné, ce type doit substituer la méthode Equals. De telles implémentations de la méthode Equals doivent retourner les mêmes résultats que l'opérateur d'égalité. Suivez ces indications afin de garantir que le code de la bibliothèque de classes utilisant Equals (notamment ArrayList et Hashtable) se comporte de manière cohérente avec le mode d'utilisation de l'opérateur d'égalité par le code d'application. Les indications suivantes concernent l'implémentation d'un type valeur :
  • Pensez à substituer Equals afin d'améliorer les performances par rapport à celles qui sont fournies par l'implémentation par défaut de Equals sur ValueType.

  • Si vous substituez Equals et si le langage prend en charge la surcharge d'opérateur, vous devez surcharger l'opérateur d'égalité pour votre type valeur.

Les indications suivantes concernent l'implémentation d'un type référence :
  • Pensez à substituer Equals sur un type référence si la sémantique du type se base sur le fait que le type représente une ou plusieurs valeurs.

  • La plupart des types référence ne doivent pas surcharger l'opérateur d'égalité, même s'ils substituent la méthode Equals. Cependant, si vous implémentez un type référence qui doit avoir une sémantique de valeur, telle qu'un type nombre complexe, vous devez substituer l'opérateur d'égalité.

Exemple

L'exemple de code suivant compare l'instance en cours à un autre objet.

Visual Basic
Imports System

Public Class Sample
    
    Sub Method()
        Dim Obj1 As New Object()
        Dim Obj2 As New Object()
        Console.WriteLine(Obj1.Equals(Obj2)) '===> false
        Obj2 = Obj1
        Console.WriteLine(Obj1.Equals(Obj2)) '===> true
    End Sub 'Method 
End Class 'Sample
C#
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
    }
}
C++
#using <System.DLL>

using namespace System;
ref class Sample
{
private:
   void Method()
   {
      Object^ Obj1 = gcnew Object;
      Object^ Obj2 = gcnew Object;
      Console::WriteLine( Obj1->Equals( Obj2 ) ); //===> false
      Obj2 = Obj1;
      Console::WriteLine( Obj1->Equals( Obj2 ) ); //===> true
   }

};
J#
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

L'exemple suivant illustre une classe Point qui substitue la méthode Equals afin de fournir l'égalité des valeurs et une classe Point3D dérivée de Point. Comme la substitution de Equals effectuée par Point est la première dans la chaîne d'héritage à introduire l'égalité des valeurs, la méthode Equals de la classe de base (qui est héritée de Object et vérifie l'égalité des références) n'est pas appelée. Cependant, Point3D.Equals appelle Point.Equals, car Point implémente Equals de manière à fournir l'égalité des valeurs.

C#
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;
   }
}
C++
using namespace System;
ref class Point: public Object
{
protected:
   int x;
   int y;

public:
   Point()
   {
      this->x = 0;
      this->y = 0;
   }

   Point( int X, int Y )
   {
      this->x = X;
      this->y = Y;
   }

   virtual bool Equals( Object^ obj ) override
   {
      
      //Check for null and compare run-time types.
      if ( obj == nullptr || GetType() != obj->GetType() )
            return false;

      Point ^ p = dynamic_cast<Point^>(obj);
      return (x == p->x) && (y == p->y);
   }

   virtual int GetHashCode() override
   {
      return x ^ y;
   }

};

ref class Point3D: public Point
{
private:
   int z;

public:
   Point3D( int X, int Y, int Z )
   {
      this->x = X;
      this->y = Y;
      this->z = Z;
   }

   virtual bool Equals( Object^ obj ) override
   {
      return Point::Equals( obj ) && z == (dynamic_cast<Point3D^>(obj))->z;
   }

   virtual int GetHashCode() override
   {
      return Point::GetHashCode() ^ z;
   }

};
JScript
import System;
import System.Drawing

class Point extends Object {
   var x : int;
   var y : int;

   public override function Equals(obj : Object) : Boolean {
      //Check for null and compare run-time types.
      if (obj == null || GetType() != obj.GetType()){
           return false;
      }
      var p : Point = Point(obj);
      return (x == p.x) && (y == p.y);
   }

   public override function GetHashCode() : int {
      return x ^ y;
   }
}

class Point3D extends Point {
   var z : int;

   public override function Equals(obj : Object) : Boolean{
      return super.Equals(obj) && z == (Point3D(obj)).z;
   }

   public override function GetHashCode() : int {
      return super.GetHashCode() ^ z;
   }
}

La méthode Point.Equals vérifie que l'argument obj n'est pas référence Null (Nothing en Visual Basic) et qu'il fait référence à une instance du même type que cet objet. Si une de ces vérifications échoue, la méthode retourne false.

La méthode Equals utilise GetType pour déterminer si les types d'exécution des deux objets sont identiques. (Remarquez que typeof n'est pas utilisé ici, car il retourne le type statique.) Si la méthode a utilisé une vérification sous la forme obj is Point, elle retourne true si obj est une instance d'une classe dérivée de Point, même si obj et l'instance en cours n'ont pas le même type au moment de l'exécution. Après avoir vérifié que les deux objets sont du même type, la méthode effectue un cast de obj en type Point et retourne le résultat de la comparaison des variables de l'instance des deux objets.

Dans Point3D.Equals, la méthode Equals héritée est appelée avant toute autre action. La méthode Equals héritée vérifie que obj n'est pas référence Null (Nothing en Visual Basic), que obj est une instance de la même classe que cet objet et que les variables de l'instance héritée correspondent. La méthode ne compare les variables de l'instance introduites dans la classe dérivée que si le Equals hérité retourne true. En particulier, le cast en Point3D n'est pas exécuté, à moins que obj ait été défini comme étant de type Point3D ou une classe dérivée de Point3D.

Dans l'exemple précédent, operator == (l'opérateur d'égalité) est utilisé pour comparer les différentes variables de l'instance. Dans certains cas, il convient d'utiliser la méthode Equals pour comparer les variables de l'instance dans une implémentation de Equals, comme le montre l'exemple de code suivant.

C#
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();
   }

}
C++
ref class Rectangle
{
private:
   Point^ a;
   Point^ b;

public:
   Rectangle( int upLeftX, int upLeftY, int downRightX, int downRightY )
   {
      this->a = gcnew Point( upLeftX,upLeftY );
      this->b = gcnew Point( downRightX,downRightY );
   }

   virtual bool Equals( Object^ obj ) override
   {
      
      // Performs an equality check on two rectangles (Point object pairs).
      if ( obj == nullptr || GetType() != obj->GetType() )
            return false;

      Rectangle^ r = dynamic_cast<Rectangle^>(obj);
      
      //Uses Equals to compare variables.
      return a->Equals( r->a ) && b->Equals( r->b );
   }

   virtual int GetHashCode() override
   {
      return a->GetHashCode() ^ b->GetHashCode();
   }

};
JScript
import System;
import System.Drawing;

class Rectangle {
   var a : Point;
   var b : Point;

   public override function Equals(obj : Object) : Boolean {
      if (obj == null || GetType() != obj.GetType()) {
           return false;
      }
      
      var r : Rectangle = Rectangle(obj);
      //Uses Equals to compare variables.
      return a.Equals(r.a) && b.Equals(r.b);
   }

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

Dans certains langages, notamment C#, la surcharge d'opérateur est prise en charge. Si un type surcharge operator ==, il doit également substituer la méthode Equals pour fournir les mêmes fonctionnalités. Cette opération est généralement accomplie en écrivant la méthode Equals en fonction de l'operator == surchargé, comme dans l'exemple de code suivant.

C#
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);
   }
}
C++
using namespace System;
public value struct Complex
{
public:
   double re;
   double im;
   virtual bool Equals( Object^ obj ) override
   {
      return (dynamic_cast<Complex^>(obj) != nullptr) && (*this == *dynamic_cast<Complex^>(obj));
   }

   virtual int GetHashCode() override
   {
      return re.GetHashCode() ^ im.GetHashCode();
   }

   static bool operator==( Complex x, Complex y )
   {
      return x.re == y.re && x.im == y.im;
   }

   static bool operator!=( Complex x, Complex y )
   {
      return  !(x == y);
   }

};

Comme Complex est une structure C# (un type valeur), il est impossible de le dériver. Par conséquent, la méthode Equals ne doit pas comparer les résultats de GetType pour chaque objet, mais peut plutôt utiliser l'opérateur is pour vérifier le type du paramètre obj.

Plates-formes

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile pour Pocket PC, Windows Mobile pour Smartphone, Windows Server 2003, Windows XP Édition Media Center, Windows XP Professionnel Édition x64, Windows XP SP2, Windows XP Starter Edition

Le .NET Framework ne prend pas en charge toutes les versions de chaque plate-forme. Pour obtenir la liste des versions prises en charge, consultez Configuration requise.

Informations de version

.NET Framework

Prise en charge dans : 2.0, 1.1, 1.0

.NET Compact Framework

Prise en charge dans : 2.0, 1.0
Voir aussi

Mots clés :


Page view tracker