Package org.apache.commons.collections4

# Class ComparatorUtils

java.lang.Object
org.apache.commons.collections4.ComparatorUtils

public class ComparatorUtils extends Object
Provides convenient static utility methods for `Comparator` objects.

Most of the functionality in this class can also be found in the `comparators` package. This class merely provides a convenient central place if you have use for more than one class in the `comparators` subpackage.

Since:
  2.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Comparator`
  `NATURAL_COMPARATOR`
  Comparator for natural sort order.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Comparator<Boolean>`
  `booleanComparator(boolean trueFirst)`
  Gets a Comparator that can sort Boolean objects.
  `static <E> Comparator<E>`
  `chainedComparator(Collection<Comparator<E>> comparators)`
  Gets a comparator that compares using a collection of `Comparator`s, applied in (default iterator) sequence until one returns not equal or the collection is exhausted.
  `static <E> Comparator<E>`
  `chainedComparator(Comparator<E>... comparators)`
  Gets a comparator that compares using an array of `Comparator`s, applied in sequence until one returns not equal or the array is exhausted.
  `static <E> E`
  `max(E o1, E o2, Comparator<E> comparator)`
  Returns the largest of the given objects according to the given comparator, returning the second object if the comparator returns equal.
  `static <E> E`
  `min(E o1, E o2, Comparator<E> comparator)`
  Returns the smallest of the given objects according to the given comparator, returning the second object if the comparator returns equal.
  `static <E extends Comparable<? super E>>
  Comparator<E>`
  `naturalComparator()`
  Gets a comparator that uses the natural order of the objects.
  `static <E> Comparator<E>`
  `nullHighComparator(Comparator<E> comparator)`
  Gets a Comparator that controls the comparison of `null` values.
  `static <E> Comparator<E>`
  `nullLowComparator(Comparator<E> comparator)`
  Gets a Comparator that controls the comparison of `null` values.
  `static <E> Comparator<E>`
  `reversedComparator(Comparator<E> comparator)`
  Gets a comparator that reverses the order of the given comparator.
  `static <I, O> Comparator<I>`
  `transformedComparator(Comparator<O> comparator, Transformer<? super I,? extends O> transformer)`
  Gets a Comparator that passes transformed objects to the given comparator.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### NATURAL_COMPARATOR

    public static final Comparator NATURAL_COMPARATOR
    Comparator for natural sort order.
    See Also:
      - `ComparableComparator.comparableComparator()`

- ## Method Details

  - ### booleanComparator

    public static Comparator<Boolean> booleanComparator(boolean trueFirst)
    Gets a Comparator that can sort Boolean objects.

    The parameter specifies whether true or false is sorted first.

    The comparator throws NullPointerException if a null value is compared.

    Parameters:
      `trueFirst` - when `true`, sort `true` `Boolean`s before `false` `Boolean`s.
    Returns:
      a comparator that sorts booleans

  - ### chainedComparator

    public static <E> Comparator<E> chainedComparator(Collection<Comparator<E>> comparators)
    Gets a comparator that compares using a collection of `Comparator`s, applied in (default iterator) sequence until one returns not equal or the collection is exhausted.
    Type Parameters:
      `E` - the object type to compare
    Parameters:
      `comparators` - The comparators to use, not null or empty or containing nulls
    Returns:
      A `ComparatorChain` formed from the input comparators
    Throws:
      `NullPointerException` - if comparators collection is null or contains a null
      `ClassCastException` - if the comparators collection contains the wrong object type
    See Also:
      - `ComparatorChain`

  - ### chainedComparator

    public static <E> Comparator<E> chainedComparator(Comparator<E>... comparators)
    Gets a comparator that compares using an array of `Comparator`s, applied in sequence until one returns not equal or the array is exhausted.
    Type Parameters:
      `E` - the object type to compare
    Parameters:
      `comparators` - The comparators to use, not null or empty or containing nulls
    Returns:
      A `ComparatorChain` formed from the input comparators
    Throws:
      `NullPointerException` - if comparators array is null or contains a null
    See Also:
      - `ComparatorChain`

  - ### max

    public static <E> E max(E o1, E o2, Comparator<E> comparator)
    Returns the largest of the given objects according to the given comparator, returning the second object if the comparator returns equal.
    Type Parameters:
      `E` - the object type to compare
    Parameters:
      `o1` - The first object to compare
      `o2` - The second object to compare
      `comparator` - The sort order to use
    Returns:
      the larger of the two objects

  - ### min

    public static <E> E min(E o1, E o2, Comparator<E> comparator)
    Returns the smallest of the given objects according to the given comparator, returning the second object if the comparator returns equal.
    Type Parameters:
      `E` - the object type to compare
    Parameters:
      `o1` - The first object to compare
      `o2` - The second object to compare
      `comparator` - The sort order to use
    Returns:
      the smaller of the two objects

  - ### naturalComparator

    public static <E extends Comparable<? super E>> Comparator<E> naturalComparator()
    Gets a comparator that uses the natural order of the objects.
    Type Parameters:
      `E` - the object type to compare
    Returns:
      a comparator which uses natural order

  - ### nullHighComparator

    public static <E> Comparator<E> nullHighComparator(Comparator<E> comparator)
    Gets a Comparator that controls the comparison of `null` values.

    The returned comparator will consider a null value to be greater than any nonnull value, and equal to any other null value. Two nonnull values will be evaluated with the given comparator.

    Type Parameters:
      `E` - the object type to compare
    Parameters:
      `comparator` - The comparator that wants to allow nulls
    Returns:
      a version of that comparator that allows nulls
    See Also:
      - `NullComparator`

  - ### nullLowComparator

    public static <E> Comparator<E> nullLowComparator(Comparator<E> comparator)
    Gets a Comparator that controls the comparison of `null` values.

    The returned comparator will consider a null value to be less than any nonnull value, and equal to any other null value. Two nonnull values will be evaluated with the given comparator.

    Type Parameters:
      `E` - the object type to compare
    Parameters:
      `comparator` - The comparator that wants to allow nulls
    Returns:
      a version of that comparator that allows nulls
    See Also:
      - `NullComparator`

  - ### reversedComparator

    public static <E> Comparator<E> reversedComparator(Comparator<E> comparator)
    Gets a comparator that reverses the order of the given comparator.
    Type Parameters:
      `E` - the object type to compare
    Parameters:
      `comparator` - The comparator to reverse
    Returns:
      a comparator that reverses the order of the input comparator
    See Also:
      - `ReverseComparator`

  - ### transformedComparator

    public static <I, O> Comparator<I> transformedComparator(Comparator<O> comparator, Transformer<? super I,? extends O> transformer)
    Gets a Comparator that passes transformed objects to the given comparator.

    Objects passed to the returned comparator will first be transformed by the given transformer before they are compared by the given comparator.

    Type Parameters:
      `I` - the input object type of the transformed comparator
      `O` - the object type of the decorated comparator
    Parameters:
      `comparator` - The sort order to use
      `transformer` - The transformer to use
    Returns:
      a comparator that transforms its input objects before comparing them
    See Also:
      - `TransformingComparator`