Index: sdk/lib/core/object.dart |
diff --git a/sdk/lib/core/object.dart b/sdk/lib/core/object.dart |
index c7f3fdb12e455e9cf3789960c41d16da271116ec..fe701386553af7f9643f2eb1489230607bf378ff 100644 |
--- a/sdk/lib/core/object.dart |
+++ b/sdk/lib/core/object.dart |
@@ -32,7 +32,7 @@ class Object { |
* The equality operator. |
* |
* The default behavior for all [Object]s is to return true if and |
- * only if [:this:] and [other] are the same object. |
+ * only if `this` and [other] are the same object. |
* |
* Override this method to specify a different equality relation on |
* a class. The overriding method must still be an equivalence relation. |
@@ -49,9 +49,9 @@ class Object { |
* * Transitive: For all objects `o1`, `o2`, and `o3`, if `o1 == o2` and |
* `o2 == o3` are true, then `o1 == o3` must be true. |
* |
- * The method should also be consistent over time, so equality of two objects |
- * should not change over time, or at least only change if one of the objects |
- * was modified. |
+ * The method should also be consistent over time, |
+ * so whether two objects are equal should only change |
+ * if at least one of the objects were modified. |
floitsch
2017/02/22 16:48:00
was
Lasse Reichstein Nielsen
2017/02/22 17:44:13
I would say that "were" binds to the nearest prece
floitsch
2017/02/22 17:46:45
The subject is "one", and the "of the objects" is
Lasse Reichstein Nielsen
2017/02/23 08:26:11
Done.
|
* |
* If a subclass overrides the equality operator it should override |
* the [hashCode] method as well to maintain consistency. |
@@ -59,16 +59,34 @@ class Object { |
external bool operator==(other); |
/** |
- * Get a hash code for this object. |
+ * The hash code for this object. |
* |
- * All objects have hash codes. Hash codes are guaranteed to be the |
- * same for objects that are equal when compared using the equality |
- * operator [:==:]. Other than that there are no guarantees about |
- * the hash codes. They will not be consistent between runs and |
- * there are no distribution guarantees. |
- * |
- * If a subclass overrides [hashCode] it should override the |
- * equality operator as well to maintain consistency. |
+ * A hash code is a single integer which represents the state of the object |
+ * that affects [==] comparisons. |
+ * |
+ * All objects have hash codes. |
+ * The default hash code represents only the identity of the object, |
+ * the same way as the default [==] implementation only considers objects |
+ * equal to themselves (see [identityHashCode]). |
floitsch
2017/02/22 16:48:00
identical to themselves
Lasse Reichstein Nielsen
2017/02/22 17:44:13
All objects are identical to themselves, the defau
floitsch
2017/02/22 17:46:45
Then change it to: equal to themselves if they are
Lasse Reichstein Nielsen
2017/02/23 08:26:11
That would be redundant - objects are identical to
|
+ * |
+ * If [==] is overridden to use the object state instead, |
+ * the hash code must also be changed to represent that state. |
+ * |
+ * Hash codes must be the same for objects that are equal to each other |
+ * according to [==]. |
+ * The hash code of an object should only change if the object changes |
+ * in a way that affects equality. |
+ * There are no further requirements for the hash codes. |
+ * They need not be consistent between executions of the same program |
+ * and there are no distribution guarantees. |
+ * |
+ * Objects that are not equal are allowed to have the same hash code, |
+ * it is even technically allowed that all instances have the same hash code, |
+ * but if clashes happen too often, it may reduce the efficiency of hash-based |
+ * data structures like [HashSet] or [HashMap]. |
+ * |
+ * If a subclass overrides [hashCode], it should override the |
+ * [==] operator as well to maintain consistency. |
*/ |
external int get hashCode; |