org.organicdesign.fp.collections

Interface Equator<T>

All Known Subinterfaces:

ComparisonContext<T>

All Known Implementing Classes:

ComparisonContext.CompCtx, Equator.Equat, RangeOfInt.Equat

public interface Equator<T>

An Equator represents an equality context in a way that is analgous to the java.util.Comparator interface. Comparing Objects is Relative This will need to be passed to Hash-based collections the way a Comparator is passed to tree-based ones. The method names hash() and eq() are intentionally elisions of hashCode() and equals() so that your IDE will suggest the shorter name as you start typing which is almost always what you want. You want the hash() and eq() methods because that's how Equators compare things. You don't want an equator's .hashCode() or .equals() methods because those are for comparing *Equators* and are inherited from java.lang.Object. I'd deprecate those methods, but you can't do that on an interface. A common mistake is to implement an Equator, ComparisonContext, or Comparator as an anonymous class or lambda, then be surprised when it is can't be serialized, or is deserialized as null. These one-off classes are often singletons, which are easiest to serialize as enums. If your implementation requires generic type parameters, observe how defaultEquator() tricks the type system into using generic type parameters (correctly) with an enum.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Equator.Comp
static class	Equator.Equat

Method Summary

Modifier and Type	Method and Description
static <T> Comparator<T>	defaultComparator()
static <T> Equator<T>	defaultEquator()
static int	doCompare(Comparable<Object> o1, Comparable<Object> o2) This is the guts of building a comparator from Comparables.
boolean	eq(T o1, T o2) Determines whether two objects are equal.
int	hash(T t) An integer digest used for very quick "can-equal" testing.
default boolean	neq(T o1, T o2) Returns true if two objects are NOT equal.

Method Detail

defaultEquator

static <T> Equator<T> defaultEquator()

defaultComparator

static <T> Comparator<T> defaultComparator()

doCompare

static int doCompare(Comparable<Object> o1,
                     Comparable<Object> o2)

This is the guts of building a comparator from Comparables.

hash

int hash(T t)

An integer digest used for very quick "can-equal" testing. This method MUST return equal hash codes for equal objects. It should USUALLY return unequal hash codes for unequal objects. You should not change mutable objects while you rely on their hash codes. That said, if a mutable object's internal state changes, the hash code generally must change to reflect the new state. The name of this method is short so that auto-complete can offer it before hashCode().

eq

boolean eq(T o1,
           T o2)

Determines whether two objects are equal. The name of this method is short so that auto-complete can offer it before equals(). You can do anything you want here, but consider having null == null but null != anything else.

Returns:

true if this Equator considers the two objects to be equal.

neq

default boolean neq(T o1,
                    T o2)

Returns true if two objects are NOT equal. By default, just delegates to eq(Object, Object) and reverses the result.

Returns:

true if this Equator considers the two objects to NOT be equal.