org.apache.commons.collections4.functors

## Class ComparatorPredicate<T>

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

- All Implemented Interfaces:
    Serializable, Predicate<T>

      public class ComparatorPredicate<T>
      extends Object
      implements Predicate<T>, 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 used in the following way:

       ComparatorPredicate.comparatorPredicate(ONE, comparator).evaluate(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).evaluate(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
  Version:
    $Id: ComparatorPredicate.java 1477798 2013-04-30 19:49:02Z tn $
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ComparatorPredicate.Criterion`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> Predicate<T>` | `comparatorPredicate(T object, Comparator<T> comparator)` Factory to create the comparator predicate
    `static <T> Predicate<T>` | `comparatorPredicate(T object, Comparator<T> comparator, ComparatorPredicate.Criterion criterion)` Factory to create the comparator predicate
    `boolean` | `evaluate(T target)` Evaluates the predicate.

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

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

- - ### Constructor Detail

    - #### 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 Detail

    - #### comparatorPredicate

          public static <T> Predicate<T> comparatorPredicate(T object,
                                             Comparator<T> comparator)

      Factory to create 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:
        `IllegalArgumentException` - if comparator is null

    - #### comparatorPredicate

          public static <T> Predicate<T> comparatorPredicate(T object,
                                             Comparator<T> comparator,
                                             ComparatorPredicate.Criterion criterion)

      Factory to create 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:
        `IllegalArgumentException` - if comparator is null of criterion is invalid

    - #### evaluate

          public boolean evaluate(T target)

      Evaluates the predicate. The predicate evaluates to `true` in the following cases:
      - `comparator.compare(object, input) == 0 && criterion == EQUAL`
      - `comparator.compare(object, input) < 0 && criterion == LESS`
      - `comparator.compare(object, input) > 0 && criterion == GREATER`
      - `comparator.compare(object, input) >= 0 && criterion == GREATER_OR_EQUAL`
      - `comparator.compare(object, input) <= 0 && criterion == LESS_OR_EQUAL`
      Specified by:
        `evaluate` 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.evaluate(java.lang.Object)`, `Comparator.compare(java.lang.Object first, java.lang.Object second)`

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.