Interface Hasher

A strategy for hashing values and comparing them for equivalence.

The PhpCommon\Comparison\Hasher::hash() method, introduced by this interface, is intended to provide a means for performing fast inequivalence checks and efficient insertion and lookup in hash-based data structures. This method is always consistent with PhpCommon\Comparison\Equivalence::equivalent(), which means that for any references $x and $y, if equivalent($x, $y), then hash($x) === hash($y). However, if equivalence($x, $y) evaluates to false, hash($x) === hash($y) may still be true. Hence why the hash() method is suitable for inequivalence checks, but not equivalence checks.

In accordance with PhpCommon\Comparison\Equivalence, a PhpCommon\Comparison\Hasher can be either generic or type-specific. For that reason, caution should be exercised to ensure the values passed to the methods PhpCommon\Comparison\Equivalence::equivalent() and PhpCommon\Comparison\Hasher::hash() match the type of values supported by the implementing class. Otherwise, an exception may be thrown.