1 /*
2 * Copyright (C) 2007 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.base;
16
17 import com.google.common.annotations.GwtCompatible;
18 import com.google.errorprone.annotations.CanIgnoreReturnValue;
19 import javax.annotation.CheckForNull;
20 import org.checkerframework.checker.nullness.qual.Nullable;
21
22 /**
23 * Legacy version of {@link java.util.function.Predicate java.util.function.Predicate}. Determines a
24 * true or false value for a given input.
25 *
26 * <p>As this interface extends {@code java.util.function.Predicate}, an instance of this type may
27 * be used as a {@code Predicate} directly. To use a {@code java.util.function.Predicate} where a
28 * {@code com.google.common.base.Predicate} is expected, use the method reference {@code
29 * predicate::test}.
30 *
31 * <p>This interface is now a legacy type. Use {@code java.util.function.Predicate} (or the
32 * appropriate primitive specialization such as {@code IntPredicate}) instead whenever possible.
33 * Otherwise, at least reduce <i>explicit</i> dependencies on this type by using lambda expressions
34 * or method references instead of classes, leaving your code easier to migrate in the future.
35 *
36 * <p>The {@link Predicates} class provides common predicates and related utilities.
37 *
38 * <p>See the Guava User Guide article on <a
39 * href="https://github.com/google/guava/wiki/FunctionalExplained">the use of {@code Predicate}</a>.
40 *
41 * @author Kevin Bourrillion
42 * @since 2.0
43 */
44 @FunctionalInterface
45 @GwtCompatible
46 @ElementTypesAreNonnullByDefault
47 public interface Predicate<T extends @Nullable Object> extends java.util.function.Predicate<T> {
48 /**
49 * Returns the result of applying this predicate to {@code input} (Java 8 users, see notes in the
50 * class documentation above). This method is <i>generally expected</i>, but not absolutely
51 * required, to have the following properties:
52 *
53 * <ul>
54 * <li>Its execution does not cause any observable side effects.
55 * <li>The computation is <i>consistent with equals</i>; that is, {@link Objects#equal
56 * Objects.equal}{@code (a, b)} implies that {@code predicate.apply(a) ==
57 * predicate.apply(b))}.
58 * </ul>
59 *
60 * @throws NullPointerException if {@code input} is null and this predicate does not accept null
61 * arguments
62 */
63 @CanIgnoreReturnValue
64 boolean apply(@ParametricNullness T input);
65
66 /**
67 * Indicates whether another object is equal to this predicate.
68 *
69 * <p>Most implementations will have no reason to override the behavior of {@link Object#equals}.
70 * However, an implementation may also choose to return {@code true} whenever {@code object} is a
71 * {@link Predicate} that it considers <i>interchangeable</i> with this one. "Interchangeable"
72 * <i>typically</i> means that {@code this.apply(t) == that.apply(t)} for all {@code t} of type
73 * {@code T}). Note that a {@code false} result from this method does not imply that the
74 * predicates are known <i>not</i> to be interchangeable.
75 */
76 @Override
77 boolean equals(@CheckForNull Object object);
78
79 @Override
80 default boolean test(@ParametricNullness T input) {
81 return apply(input);
82 }
83 }