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 static com.google.common.base.Preconditions.checkNotNull;
18
19 import com.google.common.annotations.Beta;
20 import com.google.common.annotations.GwtCompatible;
21 import com.google.common.annotations.GwtIncompatible;
22 import java.io.Serializable;
23 import java.util.ArrayList;
24 import java.util.Arrays;
25 import java.util.Collection;
26 import java.util.List;
27 import java.util.regex.Pattern;
28 import org.checkerframework.checker.nullness.qual.Nullable;
29
30 /**
31 * Static utility methods pertaining to {@code Predicate} instances.
32 *
33 * <p>All methods return serializable predicates as long as they're given serializable parameters.
34 *
35 * <p>See the Guava User Guide article on <a
36 * href="https://github.com/google/guava/wiki/FunctionalExplained">the use of {@code Predicate}</a>.
37 *
38 * @author Kevin Bourrillion
39 * @since 2.0
40 */
41 @GwtCompatible(emulated = true)
42 public final class Predicates {
43 private Predicates() {}
44
45 // TODO(kevinb): considering having these implement a VisitablePredicate
46 // interface which specifies an accept(PredicateVisitor) method.
47
48 /** Returns a predicate that always evaluates to {@code true}. */
49 @GwtCompatible(serializable = true)
50 public static <T> Predicate<T> alwaysTrue() {
51 return ObjectPredicate.ALWAYS_TRUE.withNarrowedType();
52 }
53
54 /** Returns a predicate that always evaluates to {@code false}. */
55 @GwtCompatible(serializable = true)
56 public static <T> Predicate<T> alwaysFalse() {
57 return ObjectPredicate.ALWAYS_FALSE.withNarrowedType();
58 }
59
60 /**
61 * Returns a predicate that evaluates to {@code true} if the object reference being tested is
62 * null.
63 */
64 @GwtCompatible(serializable = true)
65 public static <T> Predicate<T> isNull() {
66 return ObjectPredicate.IS_NULL.withNarrowedType();
67 }
68
69 /**
70 * Returns a predicate that evaluates to {@code true} if the object reference being tested is not
71 * null.
72 */
73 @GwtCompatible(serializable = true)
74 public static <T> Predicate<T> notNull() {
75 return ObjectPredicate.NOT_NULL.withNarrowedType();
76 }
77
78 /**
79 * Returns a predicate that evaluates to {@code true} if the given predicate evaluates to {@code
80 * false}.
81 */
82 public static <T> Predicate<T> not(Predicate<T> predicate) {
83 return new NotPredicate<T>(predicate);
84 }
85
86 /**
87 * Returns a predicate that evaluates to {@code true} if each of its components evaluates to
88 * {@code true}. The components are evaluated in order, and evaluation will be "short-circuited"
89 * as soon as a false predicate is found. It defensively copies the iterable passed in, so future
90 * changes to it won't alter the behavior of this predicate. If {@code components} is empty, the
91 * returned predicate will always evaluate to {@code true}.
92 */
93 public static <T> Predicate<T> and(Iterable<? extends Predicate<? super T>> components) {
94 return new AndPredicate<T>(defensiveCopy(components));
95 }
96
97 /**
98 * Returns a predicate that evaluates to {@code true} if each of its components evaluates to
99 * {@code true}. The components are evaluated in order, and evaluation will be "short-circuited"
100 * as soon as a false predicate is found. It defensively copies the array passed in, so future
101 * changes to it won't alter the behavior of this predicate. If {@code components} is empty, the
102 * returned predicate will always evaluate to {@code true}.
103 */
104 @SafeVarargs
105 public static <T> Predicate<T> and(Predicate<? super T>... components) {
106 return new AndPredicate<T>(defensiveCopy(components));
107 }
108
109 /**
110 * Returns a predicate that evaluates to {@code true} if both of its components evaluate to {@code
111 * true}. The components are evaluated in order, and evaluation will be "short-circuited" as soon
112 * as a false predicate is found.
113 */
114 public static <T> Predicate<T> and(Predicate<? super T> first, Predicate<? super T> second) {
115 return new AndPredicate<T>(Predicates.<T>asList(checkNotNull(first), checkNotNull(second)));
116 }
117
118 /**
119 * Returns a predicate that evaluates to {@code true} if any one of its components evaluates to
120 * {@code true}. The components are evaluated in order, and evaluation will be "short-circuited"
121 * as soon as a true predicate is found. It defensively copies the iterable passed in, so future
122 * changes to it won't alter the behavior of this predicate. If {@code components} is empty, the
123 * returned predicate will always evaluate to {@code false}.
124 */
125 public static <T> Predicate<T> or(Iterable<? extends Predicate<? super T>> components) {
126 return new OrPredicate<T>(defensiveCopy(components));
127 }
128
129 /**
130 * Returns a predicate that evaluates to {@code true} if any one of its components evaluates to
131 * {@code true}. The components are evaluated in order, and evaluation will be "short-circuited"
132 * as soon as a true predicate is found. It defensively copies the array passed in, so future
133 * changes to it won't alter the behavior of this predicate. If {@code components} is empty, the
134 * returned predicate will always evaluate to {@code false}.
135 */
136 @SafeVarargs
137 public static <T> Predicate<T> or(Predicate<? super T>... components) {
138 return new OrPredicate<T>(defensiveCopy(components));
139 }
140
141 /**
142 * Returns a predicate that evaluates to {@code true} if either of its components evaluates to
143 * {@code true}. The components are evaluated in order, and evaluation will be "short-circuited"
144 * as soon as a true predicate is found.
145 */
146 public static <T> Predicate<T> or(Predicate<? super T> first, Predicate<? super T> second) {
147 return new OrPredicate<T>(Predicates.<T>asList(checkNotNull(first), checkNotNull(second)));
148 }
149
150 /**
151 * Returns a predicate that evaluates to {@code true} if the object being tested {@code equals()}
152 * the given target or both are null.
153 */
154 public static <T> Predicate<T> equalTo(@Nullable T target) {
155 return (target == null) ? Predicates.<T>isNull() : new IsEqualToPredicate<T>(target);
156 }
157
158 /**
159 * Returns a predicate that evaluates to {@code true} if the object being tested is an instance of
160 * the given class. If the object being tested is {@code null} this predicate evaluates to {@code
161 * false}.
162 *
163 * <p>If you want to filter an {@code Iterable} to narrow its type, consider using {@link
164 * com.google.common.collect.Iterables#filter(Iterable, Class)} in preference.
165 *
166 * <p><b>Warning:</b> contrary to the typical assumptions about predicates (as documented at
167 * {@link Predicate#apply}), the returned predicate may not be <i>consistent with equals</i>. For
168 * example, {@code instanceOf(ArrayList.class)} will yield different results for the two equal
169 * instances {@code Lists.newArrayList(1)} and {@code Arrays.asList(1)}.
170 */
171 @GwtIncompatible // Class.isInstance
172 public static <T> Predicate<T> instanceOf(Class<?> clazz) {
173 return new InstanceOfPredicate<T>(clazz);
174 }
175
176 /**
177 * Returns a predicate that evaluates to {@code true} if the class being tested is assignable to
178 * (is a subtype of) {@code clazz}. Example:
179 *
180 * <pre>{@code
181 * List<Class<?>> classes = Arrays.asList(
182 * Object.class, String.class, Number.class, Long.class);
183 * return Iterables.filter(classes, subtypeOf(Number.class));
184 * }</pre>
185 *
186 * The code above returns an iterable containing {@code Number.class} and {@code Long.class}.
187 *
188 * @since 20.0 (since 10.0 under the incorrect name {@code assignableFrom})
189 */
190 @GwtIncompatible // Class.isAssignableFrom
191 @Beta
192 public static Predicate<Class<?>> subtypeOf(Class<?> clazz) {
193 return new SubtypeOfPredicate(clazz);
194 }
195
196 /**
197 * Returns a predicate that evaluates to {@code true} if the object reference being tested is a
198 * member of the given collection. It does not defensively copy the collection passed in, so
199 * future changes to it will alter the behavior of the predicate.
200 *
201 * <p>This method can technically accept any {@code Collection<?>}, but using a typed collection
202 * helps prevent bugs. This approach doesn't block any potential users since it is always possible
203 * to use {@code Predicates.<Object>in()}.
204 *
205 * @param target the collection that may contain the function input
206 */
207 public static <T> Predicate<T> in(Collection<? extends T> target) {
208 return new InPredicate<T>(target);
209 }
210
211 /**
212 * Returns the composition of a function and a predicate. For every {@code x}, the generated
213 * predicate returns {@code predicate(function(x))}.
214 *
215 * @return the composition of the provided function and predicate
216 */
217 public static <A, B> Predicate<A> compose(
218 Predicate<B> predicate, Function<A, ? extends B> function) {
219 return new CompositionPredicate<>(predicate, function);
220 }
221
222 /**
223 * Returns a predicate that evaluates to {@code true} if the {@code CharSequence} being tested
224 * contains any match for the given regular expression pattern. The test used is equivalent to
225 * {@code Pattern.compile(pattern).matcher(arg).find()}
226 *
227 * @throws IllegalArgumentException if the pattern is invalid
228 * @since 3.0
229 */
230 @GwtIncompatible // Only used by other GWT-incompatible code.
231 public static Predicate<CharSequence> containsPattern(String pattern) {
232 return new ContainsPatternFromStringPredicate(pattern);
233 }
234
235 /**
236 * Returns a predicate that evaluates to {@code true} if the {@code CharSequence} being tested
237 * contains any match for the given regular expression pattern. The test used is equivalent to
238 * {@code pattern.matcher(arg).find()}
239 *
240 * @since 3.0
241 */
242 @GwtIncompatible(value = "java.util.regex.Pattern")
243 public static Predicate<CharSequence> contains(Pattern pattern) {
244 return new ContainsPatternPredicate(new JdkPattern(pattern));
245 }
246
247 // End public API, begin private implementation classes.
248
249 // Package private for GWT serialization.
250 enum ObjectPredicate implements Predicate<Object> {
251 /** @see Predicates#alwaysTrue() */
252 ALWAYS_TRUE {
253 @Override
254 public boolean apply(@Nullable Object o) {
255 return true;
256 }
257
258 @Override
259 public String toString() {
260 return "Predicates.alwaysTrue()";
261 }
262 },
263 /** @see Predicates#alwaysFalse() */
264 ALWAYS_FALSE {
265 @Override
266 public boolean apply(@Nullable Object o) {
267 return false;
268 }
269
270 @Override
271 public String toString() {
272 return "Predicates.alwaysFalse()";
273 }
274 },
275 /** @see Predicates#isNull() */
276 IS_NULL {
277 @Override
278 public boolean apply(@Nullable Object o) {
279 return o == null;
280 }
281
282 @Override
283 public String toString() {
284 return "Predicates.isNull()";
285 }
286 },
287 /** @see Predicates#notNull() */
288 NOT_NULL {
289 @Override
290 public boolean apply(@Nullable Object o) {
291 return o != null;
292 }
293
294 @Override
295 public String toString() {
296 return "Predicates.notNull()";
297 }
298 };
299
300 @SuppressWarnings("unchecked") // safe contravariant cast
301 <T> Predicate<T> withNarrowedType() {
302 return (Predicate<T>) this;
303 }
304 }
305
306 /** @see Predicates#not(Predicate) */
307 private static class NotPredicate<T> implements Predicate<T>, Serializable {
308 final Predicate<T> predicate;
309
310 NotPredicate(Predicate<T> predicate) {
311 this.predicate = checkNotNull(predicate);
312 }
313
314 @Override
315 public boolean apply(@Nullable T t) {
316 return !predicate.apply(t);
317 }
318
319 @Override
320 public int hashCode() {
321 return ~predicate.hashCode();
322 }
323
324 @Override
325 public boolean equals(@Nullable Object obj) {
326 if (obj instanceof NotPredicate) {
327 NotPredicate<?> that = (NotPredicate<?>) obj;
328 return predicate.equals(that.predicate);
329 }
330 return false;
331 }
332
333 @Override
334 public String toString() {
335 return "Predicates.not(" + predicate + ")";
336 }
337
338 private static final long serialVersionUID = 0;
339 }
340
341 /** @see Predicates#and(Iterable) */
342 private static class AndPredicate<T> implements Predicate<T>, Serializable {
343 private final List<? extends Predicate<? super T>> components;
344
345 private AndPredicate(List<? extends Predicate<? super T>> components) {
346 this.components = components;
347 }
348
349 @Override
350 public boolean apply(@Nullable T t) {
351 // Avoid using the Iterator to avoid generating garbage (issue 820).
352 for (int i = 0; i < components.size(); i++) {
353 if (!components.get(i).apply(t)) {
354 return false;
355 }
356 }
357 return true;
358 }
359
360 @Override
361 public int hashCode() {
362 // add a random number to avoid collisions with OrPredicate
363 return components.hashCode() + 0x12472c2c;
364 }
365
366 @Override
367 public boolean equals(@Nullable Object obj) {
368 if (obj instanceof AndPredicate) {
369 AndPredicate<?> that = (AndPredicate<?>) obj;
370 return components.equals(that.components);
371 }
372 return false;
373 }
374
375 @Override
376 public String toString() {
377 return toStringHelper("and", components);
378 }
379
380 private static final long serialVersionUID = 0;
381 }
382
383 /** @see Predicates#or(Iterable) */
384 private static class OrPredicate<T> implements Predicate<T>, Serializable {
385 private final List<? extends Predicate<? super T>> components;
386
387 private OrPredicate(List<? extends Predicate<? super T>> components) {
388 this.components = components;
389 }
390
391 @Override
392 public boolean apply(@Nullable T t) {
393 // Avoid using the Iterator to avoid generating garbage (issue 820).
394 for (int i = 0; i < components.size(); i++) {
395 if (components.get(i).apply(t)) {
396 return true;
397 }
398 }
399 return false;
400 }
401
402 @Override
403 public int hashCode() {
404 // add a random number to avoid collisions with AndPredicate
405 return components.hashCode() + 0x053c91cf;
406 }
407
408 @Override
409 public boolean equals(@Nullable Object obj) {
410 if (obj instanceof OrPredicate) {
411 OrPredicate<?> that = (OrPredicate<?>) obj;
412 return components.equals(that.components);
413 }
414 return false;
415 }
416
417 @Override
418 public String toString() {
419 return toStringHelper("or", components);
420 }
421
422 private static final long serialVersionUID = 0;
423 }
424
425 private static String toStringHelper(String methodName, Iterable<?> components) {
426 StringBuilder builder = new StringBuilder("Predicates.").append(methodName).append('(');
427 boolean first = true;
428 for (Object o : components) {
429 if (!first) {
430 builder.append(',');
431 }
432 builder.append(o);
433 first = false;
434 }
435 return builder.append(')').toString();
436 }
437
438 /** @see Predicates#equalTo(Object) */
439 private static class IsEqualToPredicate<T> implements Predicate<T>, Serializable {
440 private final T target;
441
442 private IsEqualToPredicate(T target) {
443 this.target = target;
444 }
445
446 @Override
447 public boolean apply(T t) {
448 return target.equals(t);
449 }
450
451 @Override
452 public int hashCode() {
453 return target.hashCode();
454 }
455
456 @Override
457 public boolean equals(@Nullable Object obj) {
458 if (obj instanceof IsEqualToPredicate) {
459 IsEqualToPredicate<?> that = (IsEqualToPredicate<?>) obj;
460 return target.equals(that.target);
461 }
462 return false;
463 }
464
465 @Override
466 public String toString() {
467 return "Predicates.equalTo(" + target + ")";
468 }
469
470 private static final long serialVersionUID = 0;
471 }
472
473 /** @see Predicates#instanceOf(Class) */
474 @GwtIncompatible // Class.isInstance
475 private static class InstanceOfPredicate<T> implements Predicate<T>, Serializable {
476 private final Class<?> clazz;
477
478 private InstanceOfPredicate(Class<?> clazz) {
479 this.clazz = checkNotNull(clazz);
480 }
481
482 @Override
483 public boolean apply(@Nullable T o) {
484 return clazz.isInstance(o);
485 }
486
487 @Override
488 public int hashCode() {
489 return clazz.hashCode();
490 }
491
492 @Override
493 public boolean equals(@Nullable Object obj) {
494 if (obj instanceof InstanceOfPredicate) {
495 InstanceOfPredicate<?> that = (InstanceOfPredicate<?>) obj;
496 return clazz == that.clazz;
497 }
498 return false;
499 }
500
501 @Override
502 public String toString() {
503 return "Predicates.instanceOf(" + clazz.getName() + ")";
504 }
505
506 private static final long serialVersionUID = 0;
507 }
508
509 /** @see Predicates#subtypeOf(Class) */
510 @GwtIncompatible // Class.isAssignableFrom
511 private static class SubtypeOfPredicate implements Predicate<Class<?>>, Serializable {
512 private final Class<?> clazz;
513
514 private SubtypeOfPredicate(Class<?> clazz) {
515 this.clazz = checkNotNull(clazz);
516 }
517
518 @Override
519 public boolean apply(Class<?> input) {
520 return clazz.isAssignableFrom(input);
521 }
522
523 @Override
524 public int hashCode() {
525 return clazz.hashCode();
526 }
527
528 @Override
529 public boolean equals(@Nullable Object obj) {
530 if (obj instanceof SubtypeOfPredicate) {
531 SubtypeOfPredicate that = (SubtypeOfPredicate) obj;
532 return clazz == that.clazz;
533 }
534 return false;
535 }
536
537 @Override
538 public String toString() {
539 return "Predicates.subtypeOf(" + clazz.getName() + ")";
540 }
541
542 private static final long serialVersionUID = 0;
543 }
544
545 /** @see Predicates#in(Collection) */
546 private static class InPredicate<T> implements Predicate<T>, Serializable {
547 private final Collection<?> target;
548
549 private InPredicate(Collection<?> target) {
550 this.target = checkNotNull(target);
551 }
552
553 @Override
554 public boolean apply(@Nullable T t) {
555 try {
556 return target.contains(t);
557 } catch (NullPointerException | ClassCastException e) {
558 return false;
559 }
560 }
561
562 @Override
563 public boolean equals(@Nullable Object obj) {
564 if (obj instanceof InPredicate) {
565 InPredicate<?> that = (InPredicate<?>) obj;
566 return target.equals(that.target);
567 }
568 return false;
569 }
570
571 @Override
572 public int hashCode() {
573 return target.hashCode();
574 }
575
576 @Override
577 public String toString() {
578 return "Predicates.in(" + target + ")";
579 }
580
581 private static final long serialVersionUID = 0;
582 }
583
584 /** @see Predicates#compose(Predicate, Function) */
585 private static class CompositionPredicate<A, B> implements Predicate<A>, Serializable {
586 final Predicate<B> p;
587 final Function<A, ? extends B> f;
588
589 private CompositionPredicate(Predicate<B> p, Function<A, ? extends B> f) {
590 this.p = checkNotNull(p);
591 this.f = checkNotNull(f);
592 }
593
594 @Override
595 public boolean apply(@Nullable A a) {
596 return p.apply(f.apply(a));
597 }
598
599 @Override
600 public boolean equals(@Nullable Object obj) {
601 if (obj instanceof CompositionPredicate) {
602 CompositionPredicate<?, ?> that = (CompositionPredicate<?, ?>) obj;
603 return f.equals(that.f) && p.equals(that.p);
604 }
605 return false;
606 }
607
608 @Override
609 public int hashCode() {
610 return f.hashCode() ^ p.hashCode();
611 }
612
613 @Override
614 public String toString() {
615 // TODO(cpovirk): maybe make this look like the method call does ("Predicates.compose(...)")
616 return p + "(" + f + ")";
617 }
618
619 private static final long serialVersionUID = 0;
620 }
621
622 /** @see Predicates#contains(Pattern) */
623 @GwtIncompatible // Only used by other GWT-incompatible code.
624 private static class ContainsPatternPredicate implements Predicate<CharSequence>, Serializable {
625 final CommonPattern pattern;
626
627 ContainsPatternPredicate(CommonPattern pattern) {
628 this.pattern = checkNotNull(pattern);
629 }
630
631 @Override
632 public boolean apply(CharSequence t) {
633 return pattern.matcher(t).find();
634 }
635
636 @Override
637 public int hashCode() {
638 // Pattern uses Object.hashCode, so we have to reach
639 // inside to build a hashCode consistent with equals.
640
641 return Objects.hashCode(pattern.pattern(), pattern.flags());
642 }
643
644 @Override
645 public boolean equals(@Nullable Object obj) {
646 if (obj instanceof ContainsPatternPredicate) {
647 ContainsPatternPredicate that = (ContainsPatternPredicate) obj;
648
649 // Pattern uses Object (identity) equality, so we have to reach
650 // inside to compare individual fields.
651 return Objects.equal(pattern.pattern(), that.pattern.pattern())
652 && pattern.flags() == that.pattern.flags();
653 }
654 return false;
655 }
656
657 @Override
658 public String toString() {
659 String patternString =
660 MoreObjects.toStringHelper(pattern)
661 .add("pattern", pattern.pattern())
662 .add("pattern.flags", pattern.flags())
663 .toString();
664 return "Predicates.contains(" + patternString + ")";
665 }
666
667 private static final long serialVersionUID = 0;
668 }
669
670 /** @see Predicates#containsPattern(String) */
671 @GwtIncompatible // Only used by other GWT-incompatible code.
672 private static class ContainsPatternFromStringPredicate extends ContainsPatternPredicate {
673
674 ContainsPatternFromStringPredicate(String string) {
675 super(Platform.compilePattern(string));
676 }
677
678 @Override
679 public String toString() {
680 return "Predicates.containsPattern(" + pattern.pattern() + ")";
681 }
682
683 private static final long serialVersionUID = 0;
684 }
685
686 private static <T> List<Predicate<? super T>> asList(
687 Predicate<? super T> first, Predicate<? super T> second) {
688 // TODO(kevinb): understand why we still get a warning despite @SafeVarargs!
689 return Arrays.<Predicate<? super T>>asList(first, second);
690 }
691
692 private static <T> List<T> defensiveCopy(T... array) {
693 return defensiveCopy(Arrays.asList(array));
694 }
695
696 static <T> List<T> defensiveCopy(Iterable<T> iterable) {
697 ArrayList<T> list = new ArrayList<T>();
698 for (T element : iterable) {
699 list.add(checkNotNull(element));
700 }
701 return list;
702 }
703 }