EqualityComparer<T> class

Used in various iteration methods for allowing user-defined comparisons between complex elements.

EqualityComparer exposes three different forms of comparison - equivalency, ordering, and hashing. Any of the options can be omitted when creating an EqualityComparer instance, in which case the omitted options will revert to default behavior as outlined below.

The EqualityComparer.compare field tests equivalency. Two elements of a given type are passed to the function, and the function returns whether or not the elements are deemed equal. If omitted, the function will default to checking for strict equivalency by using the == operator. (With the exception of Iterable, which will default to using BooleanConsumerExceptions.sequenceEqual.)

(left, right) => left == right;
// For iterables
(left, right) => left.sequenceEqual(right);

The EqualityComparer.hash field generates hash codes. An element is passed to the function and the function returns an integer value that represents the element's hash code. If omitted, the function will default to calling the object's hashCode property:

(value) => value.hashCode;

The EqualityComparer.sort field tests for sorting order. Two elements of a given type are passed to the function, and the function returns an integer that represents the sorting order of the elements. If the left value is lesser than the right value, the returned integer is negative. If the left value is greater than the right value, the returned integer is positive. If the two values are equal, 0 is returned. (This behavior is identical to various compareTo methods on Dart types.)

If the EqualityComparer.sort field is omitted, the function's default behavior depends on the type argument passed to EqualityComparer:

int will default to using int.compareTo
num will default to using num.compareTo
double will default to using double.compareTo
String will default to using String.compareTo
Duration will default to using Duration.compareTo
BigInt will default to using BigInt.compareTo
DateTime will default to using DateTime.compareTo
All other types will default to a non-sorting function:

(left, right) => return 0;

Constructors

EqualityComparer({Comparer<T>? comparer, Hasher<T>? hasher, Sorter<T>? sorter})

Properties

compare → Comparer<T>: final
hash → Hasher<T>: final
hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
sort → Sorter<T>: final

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

forType<T>() → EqualityComparer<T>: Returns the default EqualityComparer that has been registered for type T.
of<T extends Comparable<T>>({bool useEquals = false}) → EqualityComparer<T>: Returns an EqualityComparer where the sorter and optionally comparer methods are set to call the Comparable.compareTo method of the provided type. The hasher method is set to the default hasher behavior of calling Object.hashCode.
registerEqualityComparer<T>(EqualityComparer<T> comparer, {bool overwrite = false}) → bool: Registers an EqualityComparer object as the default comparer for type T, returning a bool stating if a comparer already exists.
tryForType<T>() → EqualityComparer<T>?: Returns the default EqualityComparer that has been registered for type T.
unregisterEqualityComparer<T>() → EqualityComparer<T>: Unregisters an EqualityComparer object as the default comparer for type T, returning the comparer object that was removed.