Package 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 Description
      static class  Equator.Comp  
      static class  Equator.Equat  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      static <T> java.util.Comparator<T> defaultComparator()  
      static <T> Equator<T> defaultEquator()  
      static int doCompare​(java.lang.Comparable<java.lang.Object> o1, java.lang.Comparable<java.lang.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> java.util.Comparator<T> defaultComparator()

      • doCompare

        static int doCompare​(java.lang.Comparable<java.lang.Object> o1,
                     java.lang.Comparable<java.lang.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.