Predicates
Date: 2016-05-24

com.google.common.base

## Class Predicates

- java.lang.Object
- - com.google.common.base.Predicates

-     @CheckReturnValue
      @GwtCompatible(emulated=true)
      public final class Predicates
      extends java.lang.Object

  Static utility methods pertaining to `Predicate` instances.

  All methods returns serializable predicates as long as they're given serializable parameters.

  See the Guava User Guide article on the use of `Predicate`.

  Since:
    2.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> Predicate<T>` | `alwaysFalse()` Returns a predicate that always evaluates to `false`.
    `static <T> Predicate<T>` | `alwaysTrue()` Returns a predicate that always evaluates to `true`.
    `static <T> Predicate<T>` | `and(java.lang.Iterable<? extends Predicate<? super T>> components)` Returns a predicate that evaluates to `true` if each of its components evaluates to `true`.
    `static <T> Predicate<T>` | `and(Predicate<? super T>... components)` Returns a predicate that evaluates to `true` if each of its components evaluates to `true`.
    `static <T> Predicate<T>` | `and(Predicate<? super T> first, Predicate<? super T> second)` Returns a predicate that evaluates to `true` if both of its components evaluate to `true`.
    `static Predicate<java.lang.Class<?>>` | `assignableFrom(java.lang.Class<?> clazz)` Returns a predicate that evaluates to `true` if the class being tested is assignable from the given class.
    `static <A,B> Predicate<A>` | `compose(Predicate<B> predicate, Function<A,? extends B> function)` Returns the composition of a function and a predicate.
    `static Predicate<java.lang.CharSequence>` | `contains(java.util.regex.Pattern pattern)` Returns a predicate that evaluates to `true` if the `CharSequence` being tested contains any match for the given regular expression pattern.
    `static Predicate<java.lang.CharSequence>` | `containsPattern(java.lang.String pattern)` Returns a predicate that evaluates to `true` if the `CharSequence` being tested contains any match for the given regular expression pattern.
    `static <T> Predicate<T>` | `equalTo(T target)` Returns a predicate that evaluates to `true` if the object being tested `equals()` the given target or both are null.
    `static <T> Predicate<T>` | `in(java.util.Collection<? extends T> target)` Returns a predicate that evaluates to `true` if the object reference being tested is a member of the given collection.
    `static Predicate<java.lang.Object>` | `instanceOf(java.lang.Class<?> clazz)` Returns a predicate that evaluates to `true` if the object being tested is an instance of the given class.
    `static <T> Predicate<T>` | `isNull()` Returns a predicate that evaluates to `true` if the object reference being tested is null.
    `static <T> Predicate<T>` | `not(Predicate<T> predicate)` Returns a predicate that evaluates to `true` if the given predicate evaluates to `false`.
    `static <T> Predicate<T>` | `notNull()` Returns a predicate that evaluates to `true` if the object reference being tested is not null.
    `static <T> Predicate<T>` | `or(java.lang.Iterable<? extends Predicate<? super T>> components)` Returns a predicate that evaluates to `true` if any one of its components evaluates to `true`.
    `static <T> Predicate<T>` | `or(Predicate<? super T>... components)` Returns a predicate that evaluates to `true` if any one of its components evaluates to `true`.
    `static <T> Predicate<T>` | `or(Predicate<? super T> first, Predicate<? super T> second)` Returns a predicate that evaluates to `true` if either of its components evaluates to `true`.

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

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

- - ### Method Detail

    - #### alwaysTrue

          @GwtCompatible(serializable=true)
          public static <T> Predicate<T> alwaysTrue()

      Returns a predicate that always evaluates to `true`.

    - #### alwaysFalse

          @GwtCompatible(serializable=true)
          public static <T> Predicate<T> alwaysFalse()

      Returns a predicate that always evaluates to `false`.

    - #### isNull

          @GwtCompatible(serializable=true)
          public static <T> Predicate<T> isNull()

      Returns a predicate that evaluates to `true` if the object reference being tested is null.

    - #### notNull

          @GwtCompatible(serializable=true)
          public static <T> Predicate<T> notNull()

      Returns a predicate that evaluates to `true` if the object reference being tested is not null.

    - #### not

          public static <T> Predicate<T> not(Predicate<T> predicate)

      Returns a predicate that evaluates to `true` if the given predicate evaluates to `false`.

    - #### and

          public static <T> Predicate<T> and(java.lang.Iterable<? extends Predicate<? super T>> components)

      Returns a predicate that evaluates to `true` if each of its components evaluates to `true`. The components are evaluated in order, and evaluation will be "short-circuited" as soon as a false predicate is found. It defensively copies the iterable passed in, so future changes to it won't alter the behavior of this predicate. If `components` is empty, the returned predicate will always evaluate to `true`.

    - #### and

          public static <T> Predicate<T> and(Predicate<? super T>... components)

      Returns a predicate that evaluates to `true` if each of its components evaluates to `true`. The components are evaluated in order, and evaluation will be "short-circuited" as soon as a false predicate is found. It defensively copies the array passed in, so future changes to it won't alter the behavior of this predicate. If `components` is empty, the returned predicate will always evaluate to `true`.

    - #### and

          public static <T> Predicate<T> and(Predicate<? super T> first,
                             Predicate<? super T> second)

      Returns a predicate that evaluates to `true` if both of its components evaluate to `true`. The components are evaluated in order, and evaluation will be "short-circuited" as soon as a false predicate is found.

    - #### or

          public static <T> Predicate<T> or(java.lang.Iterable<? extends Predicate<? super T>> components)

      Returns a predicate that evaluates to `true` if any one of its components evaluates to `true`. The components are evaluated in order, and evaluation will be "short-circuited" as soon as a true predicate is found. It defensively copies the iterable passed in, so future changes to it won't alter the behavior of this predicate. If `components` is empty, the returned predicate will always evaluate to `false`.

    - #### or

          public static <T> Predicate<T> or(Predicate<? super T>... components)

      Returns a predicate that evaluates to `true` if any one of its components evaluates to `true`. The components are evaluated in order, and evaluation will be "short-circuited" as soon as a true predicate is found. It defensively copies the array passed in, so future changes to it won't alter the behavior of this predicate. If `components` is empty, the returned predicate will always evaluate to `false`.

    - #### or

          public static <T> Predicate<T> or(Predicate<? super T> first,
                            Predicate<? super T> second)

      Returns a predicate that evaluates to `true` if either of its components evaluates to `true`. The components are evaluated in order, and evaluation will be "short-circuited" as soon as a true predicate is found.

    - #### equalTo

          public static <T> Predicate<T> equalTo(@Nullable
                                 T target)

      Returns a predicate that evaluates to `true` if the object being tested `equals()` the given target or both are null.

    - #### instanceOf

          @GwtIncompatible(value="Class.isInstance")
          public static Predicate<java.lang.Object> instanceOf(java.lang.Class<?> clazz)

      Returns a predicate that evaluates to `true` if the object being tested is an instance of the given class. If the object being tested is `null` this predicate evaluates to `false`.

      If you want to filter an `Iterable` to narrow its type, consider using `Iterables.filter(Iterable, Class)` in preference.

      Warning: contrary to the typical assumptions about predicates (as documented at `Predicate.apply(T)`), the returned predicate may not be consistent with equals. For example, `instanceOf(ArrayList.class)` will yield different results for the two equal instances `Lists.newArrayList(1)` and `Arrays.asList(1)`.

    - #### assignableFrom

          @GwtIncompatible(value="Class.isAssignableFrom")
          @Beta
          public static Predicate<java.lang.Class<?>> assignableFrom(java.lang.Class<?> clazz)

      Returns a predicate that evaluates to `true` if the class being tested is assignable from the given class. The returned predicate does not allow null inputs.
      Since:
        10.0

    - #### in

          public static <T> Predicate<T> in(java.util.Collection<? extends T> target)

      Returns a predicate that evaluates to `true` if the object reference being tested is a member of the given collection. It does not defensively copy the collection passed in, so future changes to it will alter the behavior of the predicate.

      This method can technically accept any `Collection<?>`, but using a typed collection helps prevent bugs. This approach doesn't block any potential users since it is always possible to use `Predicates.<Object>in()`.

      Parameters:
        `target` - the collection that may contain the function input

    - #### compose

          public static <A,B> Predicate<A> compose(Predicate<B> predicate,
                                   Function<A,? extends B> function)

      Returns the composition of a function and a predicate. For every `x`, the generated predicate returns `predicate(function(x))`.
      Returns:
        the composition of the provided function and predicate

    - #### containsPattern

          @GwtIncompatible(value="java.util.regex.Pattern")
          public static Predicate<java.lang.CharSequence> containsPattern(java.lang.String pattern)

      Returns a predicate that evaluates to `true` if the `CharSequence` being tested contains any match for the given regular expression pattern. The test used is equivalent to `Pattern.compile(pattern).matcher(arg).find()`
      Throws:
        `java.util.regex.PatternSyntaxException` - if the pattern is invalid
      Since:
        3.0

    - #### contains

          @GwtIncompatible(value="java.util.regex.Pattern")
          public static Predicate<java.lang.CharSequence> contains(java.util.regex.Pattern pattern)

      Returns a predicate that evaluates to `true` if the `CharSequence` being tested contains any match for the given regular expression pattern. The test used is equivalent to `pattern.matcher(arg).find()`
      Since:
        3.0