Package eu.bandm.tools.util.java

Class Comparators

java.lang.Object
eu.bandm.tools.util.java.Comparators
public abstract class Comparators extends Object
Library of constants and operations for working with object comparison functions.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    compare(double a, double b, double epsilon)
    Compares two floating-point values up to a threshold difference.
    static int
    compare(float a, float b, float epsilon)
    Compares two floating-point values up to a threshold difference.
    static <A extends Comparable<? super A>, B>
    Comparator<Map.Entry<A,B>>
    entryComparator()
    Returns a comparison function that compares map entries according to the natural ordering on their keys.
    static <A, B> Comparator<Map.Entry<A,B>>
    entryComparator(Comparator<? super A> c)
    Returns a comparison function that compares map entries according to some ordering on their keys.
    static boolean
    equals(double a, double b, double epsilon)
    Compares two floating-point values for equality up to a threshold difference.
    static boolean
    equals(float a, float b, float epsilon)
    Compares two floating-point values for equality up to a threshold difference.
    static <A> Comparator<A>
    lexical(Comparator<? super A>... dims)
    Returns a comparison function that combines the given ones in lexicographic order.
    static <A> Comparator<A>
    lexical(List<? extends Comparator<? super A>> dims)
    Returns a comparison function that combines the given ones in lexicographic order.
    static <A extends Comparable<? super A>>
    Comparator<A>
    natural()
    Returns a comparison function that is equivalent to the natural ordering.
    static <A> Comparator<A>
    neutral()
    Returns a comparison function that considers all objects equal.
    static <A extends Comparable<? super A>>
    Comparator<A>
    orNatural(@Opt Comparator<A> c)
    Returns the given comparison function if not null, or one equivalent to the natural ordering otherwise.
    static <A> Comparator<A>
    sequence(A... elems)
    Returns a comparison function that compares exactly the given elements according to their listed position.
    static <A> Comparator<A>
    sequence(List<? extends A> elems)
    Returns a comparison function that compares exactly the given elements according to their listed position.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • neutral

      public static <A> Comparator<A> neutral()
      Returns a comparison function that considers all objects equal.

      The resulting function permits null arguments.

      Type Parameters:
      A - the type of objects to compare
      Returns:
      a comparison function that returns 0 for all arguments

    • natural

      public static <A extends Comparable<? super A>> Comparator<A> natural()
      Returns a comparison function that is equivalent to the natural ordering.

      Such a function is sometimes implied in the Java standard library by a null reference. Use this factory method if an actual object is preferable.

      Type Parameters:
      A - the type of objects to compare
      Returns:
      a comparison function that behaves equivalently to Comparable.compareTo(T) if the first argument has this method, or throws a ClassCastException otherwise
      See Also:

    • lexical

      @SafeVarargs public static <A> Comparator<A> lexical(Comparator<? super A>... dims)
      Returns a comparison function that combines the given ones in lexicographic order.

      For any pair objects to compare, the given functions are tried in order: A nonzero result is final. Otherwise, the comparison continues with the next function. The overall result is zero if the functions are exhausted.

      Type Parameters:
      A - the type of objects to compare
      Parameters:
      dims - an array of comparison functions
      Returns:
      a comparison function that combines the given ones in lexicographic order

    • lexical

      public static <A> Comparator<A> lexical(List<? extends Comparator<? super A>> dims)
      Returns a comparison function that combines the given ones in lexicographic order.

      For any pair objects to compare, the given functions are tried in order: A nonzero result is final. Otherwise, the comparison continues with the next function. The overall result is zero if the functions are exhausted.

      Type Parameters:
      A - the type of objects to compare
      Parameters:
      dims - an array of comparison functions
      Returns:
      a comparison function that combines the given ones in lexicographic order

    • compare

      public static int compare(float a, float b, float epsilon)
      Compares two floating-point values up to a threshold difference.

      Behavior is unspecified if the threshold is not a positive number.

      Parameters:
      a - the first value
      b - the second value
      epsilon - the positive threshold
      Returns:
      zero if the values differ by less than the threshold; a negative number if the first value is smaller than the second by at least the threshold; a positive number if vice versa

    • equals

      public static boolean equals(float a, float b, float epsilon)
      Compares two floating-point values for equality up to a threshold difference.

      Behavior is unspecified if the threshold is not a positive number.

      Parameters:
      a - the first value
      b - the second value
      epsilon - the positive threshold
      Returns:
      true if the values differ by less than the threshold; false otherwise

    • compare

      public static int compare(double a, double b, double epsilon)
      Compares two floating-point values up to a threshold difference.

      Behavior is unspecified if the threshold is not a positive number.

      Parameters:
      a - the first value
      b - the second value
      epsilon - the positive threshold
      Returns:
      zero if the values differ by less than the threshold; a negative number if the first value is smaller than the second by at least the threshold; a positive number if vice versa

    • equals

      public static boolean equals(double a, double b, double epsilon)
      Compares two floating-point values for equality up to a threshold difference.

      Behavior is unspecified if the threshold is not a positive number.

      Parameters:
      a - the first value
      b - the second value
      epsilon - the positive threshold
      Returns:
      true if the values differ by less than the threshold; false otherwise

    • sequence

      public static <A> Comparator<A> sequence(List<? extends A> elems)
      Returns a comparison function that compares exactly the given elements according to their listed position.

      This is useful to create an ad-hoc ordering among a finite number of elements.

      Elements should not occur more than once in the given sequence. If that is the case, the first occurrence determines the ordering.

      Null elements are permitted, but not recommended.

      Type Parameters:
      A - the type of objects to compare
      Parameters:
      elems - a sequence of elements
      Returns:
      a comparison function that orders elements according to which comes first in the sequence, or throws NullPointerException for objects not found in the sequence
      Throws:
      NullPointerException - if elems is null

    • sequence

      @SafeVarargs public static <A> Comparator<A> sequence(A... elems)
      Returns a comparison function that compares exactly the given elements according to their listed position.

      This is useful to create an ad-hoc ordering among a finite number of elements.

      Elements should not occur more than once in the given sequence. If that is the case, the first occurrence determines the ordering.

      Null elements are permitted, but not recommended.

      Type Parameters:
      A - the type of objects to compare
      Parameters:
      elems - a sequence of elements
      Returns:
      a comparison function that orders elements according to which comes first in the sequence, or throws NullPointerException for objects not found in the sequence
      Throws:
      NullPointerException - if elems is null

    • entryComparator

      public static <A, B> Comparator<Map.Entry<A,B>> entryComparator(Comparator<? super A> c)
      Returns a comparison function that compares map entries according to some ordering on their keys.
      Type Parameters:
      A - the type of entry keys
      B - the type of entry values
      Parameters:
      c - the key comparator to use
      Returns:
      a comparison function that compares map entries according to the ordering of c on the respective keys

    • entryComparator

      public static <A extends Comparable<? super A>, B> Comparator<Map.Entry<A,B>> entryComparator()
      Returns a comparison function that compares map entries according to the natural ordering on their keys.
      Type Parameters:
      A - the type of entry keys
      B - the type of entry values
      Returns:
      a comparison function that compares map entries according to the natural ordering of the respective keys

    • orNatural

      public static <A extends Comparable<? super A>> Comparator<A> orNatural(@Opt @Opt Comparator<A> c)
      Returns the given comparison function if not null, or one equivalent to the natural ordering otherwise.

      A natural ordering is sometimes implied in the Java standard library by a null reference. Use this factory method if an actual object is preferable.

      Type Parameters:
      A - the type of objects to compare
      Parameters:
      c - a comparison function or null
      Returns:
      c if it is not null, natural() otherwise
      See Also: