Exporter (0) Imprimer
Développer tout

Object.Equals, méthode (Object)

Mise à jour : novembre 2007

Détermine si l'objet Object spécifié est égal à l'objet Object actuel.

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

public virtual bool Equals(
	Object obj
)
public boolean Equals(
	Object obj
)
public function Equals(
	obj : Object
) : boolean

Paramètres

obj
Type : System.Object
Object à comparer avec le Object actuel.

Valeur de retour

Type : System.Boolean
true si l'objet Object spécifié est égal à l'objet Object en cours ; sinon, false.

ExceptionCondition
NullReferenceException

Le paramètre obj est null.

L'implémentation par défaut de Equals prend en charge égalité des références pour les types référence, et l'égalité au niveau du bit pour les types valeur. L'égalité des références signifie que les références d'objets qui sont comparées font référence au même objet. L'égalité au niveau du bit signifie que les objets qui sont comparés ont la même représentation binaire.

Notez qu'un type dérivé peut substituer la méthode Equals pour implémenter l'égalité des valeurs. L'égalité des valeurs signifie que les objets comparés ont la même valeur même s'ils ont des représentations binaires différentes. Considérons, par exemple, deux objets Decimal qui représentent les nombres 1.10 et 1.1000. Les objets Decimal n'ont pas d'égalité au niveau du bit car ils ont des représentations binaires différentes pour prendre en compte le nombre différent de zéros de fin. Toutefois, les objets ont une égalité des valeurs car les nombres 1.10 et 1.1000 sont considérés comme égaux en termes de comparaison puisque les zéros de fins sont non significatifs.

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 null.

  • 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(null) 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é.

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

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


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.

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 MyClass {

  public static void Main() {
     Point point2D = new Point(5, 5);
     Point3D point3Da = new Point3D(5, 5, 2);
     Point3D point3Db = new Point3D(5, 5, 2);

     if (!point2D.Equals(point3Da)) {
        Console.WriteLine("point2D does not equal point3Da.");
     }
     if (!point3Db.Equals(point2D)) {
        Console.WriteLine("Likewise, point3Db does not equal point2D.");
     }
     if (point3Da.Equals(point3Db)) {
        Console.WriteLine("However, point3Da equals point3Db.");
     }

  } 
}
// ----------------------------------
// Output should be:
// 
// point2D does not equal point3Da.
// Likewise, point3Db does not equal point2D.
// However, point3Da equals point3Db.


La méthode Point.Equals vérifie que l'argument obj n'est pas null 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écutions 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 actuelle 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 null, 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.

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 MyClass {
   public static void Main() {

      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)) {
         Console.WriteLine("Rectangle r1 equals rectangle r2!");
      }
      if (!r2.Equals(r3)) {
         Console.WriteLine("But rectangle r2 does not equal rectangle r3.");
      }
   }
}
// ------------------------------
// Output should be:
// Rectangle r1 equals rectangle r2!
// But rectangle r2 does not equal rectangle r3.


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 du operator == surchargé, comme dans l'exemple de code suivant.

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 MyClass {

  public static void Main() {
    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.");
    }

    cmplx2.re = 4.0;

    if (cmplx1 == cmplx2) {
      Console.WriteLine("The two objects are now equal!");
    }
  }
}
// ---------------------------------
// Output should be:
//
// The two objects are not equal.
// The two objects are now equal!


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.

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

Le .NET Framework et le .NET Compact Framework ne prennent pas en charge toutes les versions de chaque plateforme. Pour obtenir la liste des versions prises en charge, consultez Configuration requise du .NET Framework.

.NET Framework

Pris en charge dans : 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Pris en charge dans : 3.5, 2.0, 1.0

XNA Framework

Pris en charge dans : 2.0, 1.0

Ajouts de la communauté

AJOUTER
Afficher:
© 2014 Microsoft