Package org.apache.commons.collections4.functors

# Class ComparatorPredicate<T>

java.lang.Object
org.apache.commons.collections4.functors.AbstractPredicate<T>
org.apache.commons.collections4.functors.ComparatorPredicate<T>

Type Parameters:
  `T` - the type of the input to the predicate.

All Implemented Interfaces:
  `Serializable`, `Predicate<T>`, `Predicate<T>`

public class ComparatorPredicate<T> extends AbstractPredicate<T> implements Serializable
Predicate that compares the input object with the one stored in the predicate using a comparator. In addition, the comparator result can be evaluated in accordance to a supplied criterion value.

In order to demonstrate the use of the predicate, the following variables are declared:

     Integer ONE = Integer.valueOf(1);
     Integer TWO = Integer.valueOf(2);

     Comparator comparator = new Comparator() {

         public int compare(Object first, Object second) {
             return ((Integer) second) - ((Integer) first);
         }

     };

Using the declared variables, the `ComparatorPredicate` can be used in the following way:

     ComparatorPredicate.comparatorPredicate(ONE, comparator).test(TWO);

The input variable `TWO` in compared to the stored variable `ONE` using the supplied `comparator`. This is the default usage of the predicate and will return `true` if the underlying comparator returns `0`. In addition to the default usage of the predicate, it is possible to evaluate the comparator's result in several ways. The following `ComparatorPredicate.Criterion` enumeration values are provided by the predicate:

- EQUAL
- GREATER
- GREATER_OR_EQUAL
- LESS
- LESS_OR_EQUAL

The following examples demonstrates how these constants can be used in order to manipulate the evaluation of a comparator result.

     ComparatorPredicate.comparatorPredicate(ONE, comparator,ComparatorPredicate.Criterion.GREATER).test(TWO);

The input variable TWO is compared to the stored variable ONE using the supplied `comparator` using the `GREATER` evaluation criterion constant. This instructs the predicate to return `true` if the comparator returns a value greater than `0`.

Since:
  4.0
See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ComparatorPredicate.Criterion`
  Enumerates the comparator criteria.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ComparatorPredicate(T object, Comparator<T> comparator, ComparatorPredicate.Criterion criterion)`
  Constructor that performs no validation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> Predicate<T>`
  `comparatorPredicate(T object, Comparator<T> comparator)`
  Creates the comparator predicate
  `static <T> Predicate<T>`
  `comparatorPredicate(T object, Comparator<T> comparator, ComparatorPredicate.Criterion criterion)`
  Creates the comparator predicate
  `boolean`
  `test(T target)`
  Evaluates the predicate.

  ### Methods inherited from class org.apache.commons.collections4.functors.AbstractPredicate

  `evaluate`

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

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

  ### Methods inherited from interface java.util.function.Predicate

  `and, negate, or`

- ## Constructor Details

  - ### ComparatorPredicate

    public ComparatorPredicate(T object, Comparator<T> comparator, ComparatorPredicate.Criterion criterion)
    Constructor that performs no validation. Use `comparatorPredicate` if you want that.
    Parameters:
      `object` - the object to compare to
      `comparator` - the comparator to use for comparison
      `criterion` - the criterion to use to evaluate comparison

- ## Method Details

  - ### comparatorPredicate

    public static <T> Predicate<T> comparatorPredicate(T object, Comparator<T> comparator)
    Creates the comparator predicate
    Type Parameters:
      `T` - the type that the predicate queries
    Parameters:
      `object` - the object to compare to
      `comparator` - the comparator to use for comparison
    Returns:
      the predicate
    Throws:
      `NullPointerException` - if comparator is null

  - ### comparatorPredicate

    public static <T> Predicate<T> comparatorPredicate(T object, Comparator<T> comparator, ComparatorPredicate.Criterion criterion)
    Creates the comparator predicate
    Type Parameters:
      `T` - the type that the predicate queries
    Parameters:
      `object` - the object to compare to
      `comparator` - the comparator to use for comparison
      `criterion` - the criterion to use to evaluate comparison
    Returns:
      the predicate
    Throws:
      `NullPointerException` - if comparator or criterion is null

  - ### test

    public boolean test(T target)
    Evaluates the predicate. The predicate evaluates to `true` in the following cases:
    - `comparator.compare(object, input) == 0 &amp;&amp; criterion == EQUAL`
    - `comparator.compare(object, input) &lt; 0 &amp;&amp; criterion == LESS`
    - `comparator.compare(object, input) &gt; 0 &amp;&amp; criterion == GREATER`
    - `comparator.compare(object, input) &gt;= 0 &amp;&amp; criterion == GREATER_OR_EQUAL`
    - `comparator.compare(object, input) &lt;= 0 &amp;&amp; criterion == LESS_OR_EQUAL`
    Specified by:
      `test` in interface `Predicate<T>`
    Specified by:
      `test` in interface `Predicate<T>`
    Parameters:
      `target` - the target object to compare to
    Returns:
      `true` if the comparison succeeds according to the selected criterion
    Throws:
      `IllegalStateException` - if the criterion is invalid (really not possible)
    See Also:
      - `Predicate.test(Object)`
      - `Comparator.compare(Object first, Object second)`