Index: lib/src/equality.dart |
diff --git a/lib/equality.dart b/lib/src/equality.dart |
similarity index 70% |
copy from lib/equality.dart |
copy to lib/src/equality.dart |
index 5911863f75e11332a7303e96688786273e66ec9d..5a0d074bd8d70b630187ecf76cd2ce13d705683e 100644 |
--- a/lib/equality.dart |
+++ b/lib/src/equality.dart |
@@ -2,51 +2,36 @@ |
// for details. All rights reserved. Use of this source code is governed by a |
// BSD-style license that can be found in the LICENSE file. |
-/** |
- * Defines equality relations on collections. |
- */ |
-library dart.pkg.collection.equality; |
- |
import "dart:collection"; |
const int _HASH_MASK = 0x7fffffff; |
-/** |
- * A generic equality relation on objects. |
- */ |
+/// A generic equality relation on objects. |
abstract class Equality<E> { |
const factory Equality() = DefaultEquality; |
- /** |
- * Compare two elements for being equal. |
- * |
- * This should be a proper equality relation. |
- */ |
+ /// Compare two elements for being equal. |
+ /// |
+ /// This should be a proper equality relation. |
bool equals(E e1, E e2); |
- /** |
- * Get a hashcode of an element. |
- * |
- * The hashcode should be compatible with [equals], so that if |
- * `equals(a, b)` then `hash(a) == hash(b)`. |
- */ |
+ /// Get a hashcode of an element. |
+ /// |
+ /// The hashcode should be compatible with [equals], so that if |
+ /// `equals(a, b)` then `hash(a) == hash(b)`. |
int hash(E e); |
- /** |
- * Test whether an object is a valid argument to [equals] and [hash]. |
- * |
- * Some implementations may be restricted to only work on specific types |
- * of objects. |
- */ |
+ /// Test whether an object is a valid argument to [equals] and [hash]. |
+ /// |
+ /// Some implementations may be restricted to only work on specific types |
+ /// of objects. |
bool isValidKey(Object o); |
} |
-/** |
- * Equality of objects that compares only the natural equality of the objects. |
- * |
- * This equality uses the objects' own [Object.==] and [Object.hashCode] for |
- * the equality. |
- */ |
+/// Equality of objects that compares only the natural equality of the objects. |
+/// |
+/// This equality uses the objects' own [Object.==] and [Object.hashCode] for |
+/// the equality. |
class DefaultEquality implements Equality { |
const DefaultEquality(); |
bool equals(Object e1, Object e2) => e1 == e2; |
@@ -54,9 +39,7 @@ class DefaultEquality implements Equality { |
bool isValidKey(Object o) => true; |
} |
-/** |
- * Equality of objects that compares only the identity of the objects. |
- */ |
+/// Equality of objects that compares only the identity of the objects. |
class IdentityEquality implements Equality { |
const IdentityEquality(); |
bool equals(Object e1, Object e2) => identical(e1, e2); |
@@ -64,11 +47,9 @@ class IdentityEquality implements Equality { |
bool isValidKey(Object o) => true; |
} |
-/** |
- * Equality on iterables. |
- * |
- * Two iterables are equal if they have the same elements in the same order. |
- */ |
+/// Equality on iterables. |
+/// |
+/// Two iterables are equal if they have the same elements in the same order. |
class IterableEquality<E> implements Equality<Iterable<E>> { |
final Equality<E> _elementEquality; |
const IterableEquality([Equality<E> elementEquality = |
@@ -106,15 +87,13 @@ class IterableEquality<E> implements Equality<Iterable<E>> { |
bool isValidKey(Object o) => o is Iterable<E>; |
} |
-/** |
- * Equality on lists. |
- * |
- * Two lists are equal if they have the same length and their elements |
- * at each index are equal. |
- * |
- * This is effectively the same as [IterableEquality] except that it |
- * accesses elements by index instead of through iteration. |
- */ |
+/// Equality on lists. |
+/// |
+/// Two lists are equal if they have the same length and their elements |
+/// at each index are equal. |
+/// |
+/// This is effectively the same as [IterableEquality] except that it |
+/// accesses elements by index instead of through iteration. |
class ListEquality<E> implements Equality<List<E>> { |
final Equality<E> _elementEquality; |
const ListEquality([Equality<E> elementEquality = const DefaultEquality()]) |
@@ -193,13 +172,11 @@ abstract class _UnorderedEquality<E, T extends Iterable<E>> |
} |
} |
-/** |
- * Equality of the elements of two iterables without considering order. |
- * |
- * Two iterables are considered equal if they have the same number of elements, |
- * and the elements of one set can be paired with the elements |
- * of the other iterable, so that each pair are equal. |
- */ |
+/// Equality of the elements of two iterables without considering order. |
+/// |
+/// Two iterables are considered equal if they have the same number of elements, |
+/// and the elements of one set can be paired with the elements |
+/// of the other iterable, so that each pair are equal. |
class UnorderedIterableEquality<E> extends _UnorderedEquality<E, Iterable<E>> { |
const UnorderedIterableEquality( |
[Equality<E> elementEquality = const DefaultEquality()]) |
@@ -208,16 +185,14 @@ class UnorderedIterableEquality<E> extends _UnorderedEquality<E, Iterable<E>> { |
bool isValidKey(Object o) => o is Iterable<E>; |
} |
-/** |
- * Equality of sets. |
- * |
- * Two sets are considered equal if they have the same number of elements, |
- * and the elements of one set can be paired with the elements |
- * of the other set, so that each pair are equal. |
- * |
- * This equality behaves the same as [UnorderedIterableEquality] except that |
- * it expects sets instead of iterables as arguments. |
- */ |
+/// Equality of sets. |
+/// |
+/// Two sets are considered equal if they have the same number of elements, |
+/// and the elements of one set can be paired with the elements |
+/// of the other set, so that each pair are equal. |
+/// |
+/// This equality behaves the same as [UnorderedIterableEquality] except that |
+/// it expects sets instead of iterables as arguments. |
class SetEquality<E> extends _UnorderedEquality<E, Set<E>> { |
const SetEquality( |
[Equality<E> elementEquality = const DefaultEquality()]) |
@@ -226,12 +201,10 @@ class SetEquality<E> extends _UnorderedEquality<E, Set<E>> { |
bool isValidKey(Object o) => o is Set<E>; |
} |
-/** |
- * Internal class used by [MapEquality]. |
- * |
- * The class represents a map entry as a single object, |
- * using a combined hashCode and equality of the key and value. |
- */ |
+/// Internal class used by [MapEquality]. |
+/// |
+/// The class represents a map entry as a single object, |
+/// using a combined hashCode and equality of the key and value. |
class _MapEntry { |
final MapEquality equality; |
final key; |
@@ -251,12 +224,10 @@ class _MapEntry { |
} |
} |
-/** |
- * Equality on maps. |
- * |
- * Two maps are equal if they have the same number of entries, and if the |
- * entries of the two maps are pairwise equal on both key and value. |
- */ |
+/// Equality on maps. |
+/// |
+/// Two maps are equal if they have the same number of entries, and if the |
+/// entries of the two maps are pairwise equal on both key and value. |
class MapEquality<K, V> implements Equality<Map<K, V>> { |
final Equality<K> _keyEquality; |
final Equality<V> _valueEquality; |
@@ -301,22 +272,20 @@ class MapEquality<K, V> implements Equality<Map<K, V>> { |
bool isValidKey(Object o) => o is Map<K, V>; |
} |
-/** |
- * Combines several equalities into a single equality. |
- * |
- * Tries each equality in order, using [Equality.isValidKey], and returns |
- * the result of the first equality that applies to the argument or arguments. |
- * |
- * For `equals`, the first equality that matches the first argument is used, |
- * and if the second argument of `equals` is not valid for that equality, |
- * it returns false. |
- * |
- * Because the equalities are tried in order, they should generally work on |
- * disjoint types. Otherwise the multi-equality may give inconsistent results |
- * for `equals(e1, e2)` and `equals(e2, e1)`. This can happen if one equality |
- * considers only `e1` a valid key, and not `e2`, but an equality which is |
- * checked later, allows both. |
- */ |
+/// Combines several equalities into a single equality. |
+/// |
+/// Tries each equality in order, using [Equality.isValidKey], and returns |
+/// the result of the first equality that applies to the argument or arguments. |
+/// |
+/// For `equals`, the first equality that matches the first argument is used, |
+/// and if the second argument of `equals` is not valid for that equality, |
+/// it returns false. |
+/// |
+/// Because the equalities are tried in order, they should generally work on |
+/// disjoint types. Otherwise the multi-equality may give inconsistent results |
+/// for `equals(e1, e2)` and `equals(e2, e1)`. This can happen if one equality |
+/// considers only `e1` a valid key, and not `e2`, but an equality which is |
+/// checked later, allows both. |
class MultiEquality<E> implements Equality<E> { |
final Iterable<Equality<E>> _equalities; |
@@ -345,34 +314,30 @@ class MultiEquality<E> implements Equality<E> { |
} |
} |
-/** |
- * Deep equality on collections. |
- * |
- * Recognizes lists, sets, iterables and maps and compares their elements using |
- * deep equality as well. |
- * |
- * Non-iterable/map objects are compared using a configurable base equality. |
- * |
- * Works in one of two modes: ordered or unordered. |
- * |
- * In ordered mode, lists and iterables are required to have equal elements |
- * in the same order. In unordered mode, the order of elements in iterables |
- * and lists are not important. |
- * |
- * A list is only equal to another list, likewise for sets and maps. All other |
- * iterables are compared as iterables only. |
- */ |
+/// Deep equality on collections. |
+/// |
+/// Recognizes lists, sets, iterables and maps and compares their elements using |
+/// deep equality as well. |
+/// |
+/// Non-iterable/map objects are compared using a configurable base equality. |
+/// |
+/// Works in one of two modes: ordered or unordered. |
+/// |
+/// In ordered mode, lists and iterables are required to have equal elements |
+/// in the same order. In unordered mode, the order of elements in iterables |
+/// and lists are not important. |
+/// |
+/// A list is only equal to another list, likewise for sets and maps. All other |
+/// iterables are compared as iterables only. |
class DeepCollectionEquality implements Equality { |
final Equality _base; |
final bool _unordered; |
const DeepCollectionEquality([Equality base = const DefaultEquality()]) |
: _base = base, _unordered = false; |
- /** |
- * Creates a deep equality on collections where the order of lists and |
- * iterables are not considered important. That is, lists and iterables are |
- * treated as unordered iterables. |
- */ |
+ /// Creates a deep equality on collections where the order of lists and |
+ /// iterables are not considered important. That is, lists and iterables are |
+ /// treated as unordered iterables. |
const DeepCollectionEquality.unordered( |
[Equality base = const DefaultEquality()]) |
: _base = base, _unordered = true; |