001 /*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.base;
018
019 import static com.google.common.base.Preconditions.checkNotNull;
020
021 import com.google.common.annotations.Beta;
022 import com.google.common.annotations.GwtCompatible;
023 import com.google.common.annotations.GwtIncompatible;
024
025 import java.io.Serializable;
026 import java.util.ArrayList;
027 import java.util.Arrays;
028 import java.util.Collection;
029 import java.util.List;
030 import java.util.regex.Pattern;
031
032 import javax.annotation.Nullable;
033
034 /**
035 * Static utility methods pertaining to {@code Predicate} instances.
036 *
037 * <p>All methods returns serializable predicates as long as they're given
038 * serializable parameters.
039 *
040 * <p>See the Guava User Guide article on <a href=
041 * "http://code.google.com/p/guava-libraries/wiki/FunctionalExplained">the
042 * use of {@code Predicate}</a>.
043 *
044 * @author Kevin Bourrillion
045 * @since 2.0 (imported from Google Collections Library)
046 */
047 @GwtCompatible(emulated = true)
048 public final class Predicates {
049 private Predicates() {}
050
051 // TODO(kevinb): considering having these implement a VisitablePredicate
052 // interface which specifies an accept(PredicateVisitor) method.
053
054 /**
055 * Returns a predicate that always evaluates to {@code true}.
056 */
057 @GwtCompatible(serializable = true)
058 public static <T> Predicate<T> alwaysTrue() {
059 return ObjectPredicate.ALWAYS_TRUE.withNarrowedType();
060 }
061
062 /**
063 * Returns a predicate that always evaluates to {@code false}.
064 */
065 @GwtCompatible(serializable = true)
066 public static <T> Predicate<T> alwaysFalse() {
067 return ObjectPredicate.ALWAYS_FALSE.withNarrowedType();
068 }
069
070 /**
071 * Returns a predicate that evaluates to {@code true} if the object reference
072 * being tested is null.
073 */
074 @GwtCompatible(serializable = true)
075 public static <T> Predicate<T> isNull() {
076 return ObjectPredicate.IS_NULL.withNarrowedType();
077 }
078
079 /**
080 * Returns a predicate that evaluates to {@code true} if the object reference
081 * being tested is not null.
082 */
083 @GwtCompatible(serializable = true)
084 public static <T> Predicate<T> notNull() {
085 return ObjectPredicate.NOT_NULL.withNarrowedType();
086 }
087
088 /**
089 * Returns a predicate that evaluates to {@code true} if the given predicate
090 * evaluates to {@code false}.
091 */
092 public static <T> Predicate<T> not(Predicate<T> predicate) {
093 return new NotPredicate<T>(predicate);
094 }
095
096 /**
097 * Returns a predicate that evaluates to {@code true} if each of its
098 * components evaluates to {@code true}. The components are evaluated in
099 * order, and evaluation will be "short-circuited" as soon as a false
100 * predicate is found. It defensively copies the iterable passed in, so future
101 * changes to it won't alter the behavior of this predicate. If {@code
102 * components} is empty, the returned predicate will always evaluate to {@code
103 * true}.
104 */
105 public static <T> Predicate<T> and(
106 Iterable<? extends Predicate<? super T>> components) {
107 return new AndPredicate<T>(defensiveCopy(components));
108 }
109
110 /**
111 * Returns a predicate that evaluates to {@code true} if each of its
112 * components evaluates to {@code true}. The components are evaluated in
113 * order, and evaluation will be "short-circuited" as soon as a false
114 * predicate is found. It defensively copies the array passed in, so future
115 * changes to it won't alter the behavior of this predicate. If {@code
116 * components} is empty, the returned predicate will always evaluate to {@code
117 * true}.
118 */
119 public static <T> Predicate<T> and(Predicate<? super T>... components) {
120 return new AndPredicate<T>(defensiveCopy(components));
121 }
122
123 /**
124 * Returns a predicate that evaluates to {@code true} if both of its
125 * components evaluate to {@code true}. The components are evaluated in
126 * order, and evaluation will be "short-circuited" as soon as a false
127 * predicate is found.
128 */
129 public static <T> Predicate<T> and(Predicate<? super T> first,
130 Predicate<? super T> second) {
131 return new AndPredicate<T>(Predicates.<T>asList(
132 checkNotNull(first), checkNotNull(second)));
133 }
134
135 /**
136 * Returns a predicate that evaluates to {@code true} if any one of its
137 * components evaluates to {@code true}. The components are evaluated in
138 * order, and evaluation will be "short-circuited" as soon as a
139 * true predicate is found. It defensively copies the iterable passed in, so
140 * future changes to it won't alter the behavior of this predicate. If {@code
141 * components} is empty, the returned predicate will always evaluate to {@code
142 * false}.
143 */
144 public static <T> Predicate<T> or(
145 Iterable<? extends Predicate<? super T>> components) {
146 return new OrPredicate<T>(defensiveCopy(components));
147 }
148
149 /**
150 * Returns a predicate that evaluates to {@code true} if any one of its
151 * components evaluates to {@code true}. The components are evaluated in
152 * order, and evaluation will be "short-circuited" as soon as a
153 * true predicate is found. It defensively copies the array passed in, so
154 * future changes to it won't alter the behavior of this predicate. If {@code
155 * components} is empty, the returned predicate will always evaluate to {@code
156 * false}.
157 */
158 public static <T> Predicate<T> or(Predicate<? super T>... components) {
159 return new OrPredicate<T>(defensiveCopy(components));
160 }
161
162 /**
163 * Returns a predicate that evaluates to {@code true} if either of its
164 * components evaluates to {@code true}. The components are evaluated in
165 * order, and evaluation will be "short-circuited" as soon as a
166 * true predicate is found.
167 */
168 public static <T> Predicate<T> or(
169 Predicate<? super T> first, Predicate<? super T> second) {
170 return new OrPredicate<T>(Predicates.<T>asList(
171 checkNotNull(first), checkNotNull(second)));
172 }
173
174 /**
175 * Returns a predicate that evaluates to {@code true} if the object being
176 * tested {@code equals()} the given target or both are null.
177 */
178 public static <T> Predicate<T> equalTo(@Nullable T target) {
179 return (target == null)
180 ? Predicates.<T>isNull()
181 : new IsEqualToPredicate<T>(target);
182 }
183
184 /**
185 * Returns a predicate that evaluates to {@code true} if the object being
186 * tested is an instance of the given class. If the object being tested
187 * is {@code null} this predicate evaluates to {@code false}.
188 *
189 * <p>If you want to filter an {@code Iterable} to narrow its type, consider
190 * using {@link com.google.common.collect.Iterables#filter(Iterable, Class)}
191 * in preference.
192 *
193 * <p><b>Warning:</b> contrary to the typical assumptions about predicates (as
194 * documented at {@link Predicate#apply}), the returned predicate may not be
195 * <i>consistent with equals</i>. For example, {@code
196 * instanceOf(ArrayList.class)} will yield different results for the two equal
197 * instances {@code Lists.newArrayList(1)} and {@code Arrays.asList(1)}.
198 */
199 @GwtIncompatible("Class.isInstance")
200 public static Predicate<Object> instanceOf(Class<?> clazz) {
201 return new InstanceOfPredicate(clazz);
202 }
203
204 /**
205 * Returns a predicate that evaluates to {@code true} if the class being
206 * tested is assignable from the given class. The returned predicate
207 * does not allow null inputs.
208 *
209 * @since 10.0
210 */
211 @GwtIncompatible("Class.isAssignableFrom")
212 @Beta
213 public static Predicate<Class<?>> assignableFrom(Class<?> clazz) {
214 return new AssignableFromPredicate(clazz);
215 }
216
217 /**
218 * Returns a predicate that evaluates to {@code true} if the object reference
219 * being tested is a member of the given collection. It does not defensively
220 * copy the collection passed in, so future changes to it will alter the
221 * behavior of the predicate.
222 *
223 * <p>This method can technically accept any {@code Collection<?>}, but using
224 * a typed collection helps prevent bugs. This approach doesn't block any
225 * potential users since it is always possible to use {@code
226 * Predicates.<Object>in()}.
227 *
228 * @param target the collection that may contain the function input
229 */
230 public static <T> Predicate<T> in(Collection<? extends T> target) {
231 return new InPredicate<T>(target);
232 }
233
234 /**
235 * Returns the composition of a function and a predicate. For every {@code x},
236 * the generated predicate returns {@code predicate(function(x))}.
237 *
238 * @return the composition of the provided function and predicate
239 */
240 public static <A, B> Predicate<A> compose(
241 Predicate<B> predicate, Function<A, ? extends B> function) {
242 return new CompositionPredicate<A, B>(predicate, function);
243 }
244
245 /**
246 * Returns a predicate that evaluates to {@code true} if the
247 * {@code CharSequence} being tested contains any match for the given
248 * regular expression pattern. The test used is equivalent to
249 * {@code Pattern.compile(pattern).matcher(arg).find()}
250 *
251 * @throws java.util.regex.PatternSyntaxException if the pattern is invalid
252 * @since 3.0
253 */
254 @GwtIncompatible(value = "java.util.regex.Pattern")
255 public static Predicate<CharSequence> containsPattern(String pattern) {
256 return new ContainsPatternPredicate(pattern);
257 }
258
259 /**
260 * Returns a predicate that evaluates to {@code true} if the
261 * {@code CharSequence} being tested contains any match for the given
262 * regular expression pattern. The test used is equivalent to
263 * {@code pattern.matcher(arg).find()}
264 *
265 * @since 3.0
266 */
267 @GwtIncompatible(value = "java.util.regex.Pattern")
268 public static Predicate<CharSequence> contains(Pattern pattern) {
269 return new ContainsPatternPredicate(pattern);
270 }
271
272 // End public API, begin private implementation classes.
273
274 // Package private for GWT serialization.
275 enum ObjectPredicate implements Predicate<Object> {
276 ALWAYS_TRUE {
277 @Override public boolean apply(@Nullable Object o) {
278 return true;
279 }
280 },
281 ALWAYS_FALSE {
282 @Override public boolean apply(@Nullable Object o) {
283 return false;
284 }
285 },
286 IS_NULL {
287 @Override public boolean apply(@Nullable Object o) {
288 return o == null;
289 }
290 },
291 NOT_NULL {
292 @Override public boolean apply(@Nullable Object o) {
293 return o != null;
294 }
295 };
296
297 @SuppressWarnings("unchecked") // these Object predicates work for any T
298 <T> Predicate<T> withNarrowedType() {
299 return (Predicate<T>) this;
300 }
301 }
302
303 /** @see Predicates#not(Predicate) */
304 private static class NotPredicate<T> implements Predicate<T>, Serializable {
305 final Predicate<T> predicate;
306
307 NotPredicate(Predicate<T> predicate) {
308 this.predicate = checkNotNull(predicate);
309 }
310 @Override
311 public boolean apply(T t) {
312 return !predicate.apply(t);
313 }
314 @Override public int hashCode() {
315 return ~predicate.hashCode();
316 }
317 @Override public boolean equals(@Nullable Object obj) {
318 if (obj instanceof NotPredicate) {
319 NotPredicate<?> that = (NotPredicate<?>) obj;
320 return predicate.equals(that.predicate);
321 }
322 return false;
323 }
324 @Override public String toString() {
325 return "Not(" + predicate.toString() + ")";
326 }
327 private static final long serialVersionUID = 0;
328 }
329
330 private static final Joiner COMMA_JOINER = Joiner.on(",");
331
332 /** @see Predicates#and(Iterable) */
333 private static class AndPredicate<T> implements Predicate<T>, Serializable {
334 private final List<? extends Predicate<? super T>> components;
335
336 private AndPredicate(List<? extends Predicate<? super T>> components) {
337 this.components = components;
338 }
339 @Override
340 public boolean apply(T t) {
341 // Avoid using the Iterator to avoid generating garbage (issue 820).
342 for (int i = 0; i < components.size(); i++) {
343 if (!components.get(i).apply(t)) {
344 return false;
345 }
346 }
347 return true;
348 }
349 @Override public int hashCode() {
350 // add a random number to avoid collisions with OrPredicate
351 return components.hashCode() + 0x12472c2c;
352 }
353 @Override public boolean equals(@Nullable Object obj) {
354 if (obj instanceof AndPredicate) {
355 AndPredicate<?> that = (AndPredicate<?>) obj;
356 return components.equals(that.components);
357 }
358 return false;
359 }
360 @Override public String toString() {
361 return "And(" + COMMA_JOINER.join(components) + ")";
362 }
363 private static final long serialVersionUID = 0;
364 }
365
366 /** @see Predicates#or(Iterable) */
367 private static class OrPredicate<T> implements Predicate<T>, Serializable {
368 private final List<? extends Predicate<? super T>> components;
369
370 private OrPredicate(List<? extends Predicate<? super T>> components) {
371 this.components = components;
372 }
373 @Override
374 public boolean apply(T t) {
375 // Avoid using the Iterator to avoid generating garbage (issue 820).
376 for (int i = 0; i < components.size(); i++) {
377 if (components.get(i).apply(t)) {
378 return true;
379 }
380 }
381 return false;
382 }
383 @Override public int hashCode() {
384 // add a random number to avoid collisions with AndPredicate
385 return components.hashCode() + 0x053c91cf;
386 }
387 @Override public boolean equals(@Nullable Object obj) {
388 if (obj instanceof OrPredicate) {
389 OrPredicate<?> that = (OrPredicate<?>) obj;
390 return components.equals(that.components);
391 }
392 return false;
393 }
394 @Override public String toString() {
395 return "Or(" + COMMA_JOINER.join(components) + ")";
396 }
397 private static final long serialVersionUID = 0;
398 }
399
400 /** @see Predicates#equalTo(Object) */
401 private static class IsEqualToPredicate<T>
402 implements Predicate<T>, Serializable {
403 private final T target;
404
405 private IsEqualToPredicate(T target) {
406 this.target = target;
407 }
408 @Override
409 public boolean apply(T t) {
410 return target.equals(t);
411 }
412 @Override public int hashCode() {
413 return target.hashCode();
414 }
415 @Override public boolean equals(@Nullable Object obj) {
416 if (obj instanceof IsEqualToPredicate) {
417 IsEqualToPredicate<?> that = (IsEqualToPredicate<?>) obj;
418 return target.equals(that.target);
419 }
420 return false;
421 }
422 @Override public String toString() {
423 return "IsEqualTo(" + target + ")";
424 }
425 private static final long serialVersionUID = 0;
426 }
427
428 /** @see Predicates#instanceOf(Class) */
429 @GwtIncompatible("Class.isInstance")
430 private static class InstanceOfPredicate
431 implements Predicate<Object>, Serializable {
432 private final Class<?> clazz;
433
434 private InstanceOfPredicate(Class<?> clazz) {
435 this.clazz = checkNotNull(clazz);
436 }
437 @Override
438 public boolean apply(@Nullable Object o) {
439 return clazz.isInstance(o);
440 }
441 @Override public int hashCode() {
442 return clazz.hashCode();
443 }
444 @Override public boolean equals(@Nullable Object obj) {
445 if (obj instanceof InstanceOfPredicate) {
446 InstanceOfPredicate that = (InstanceOfPredicate) obj;
447 return clazz == that.clazz;
448 }
449 return false;
450 }
451 @Override public String toString() {
452 return "IsInstanceOf(" + clazz.getName() + ")";
453 }
454 private static final long serialVersionUID = 0;
455 }
456
457 /** @see Predicates#assignableFrom(Class) */
458 @GwtIncompatible("Class.isAssignableFrom")
459 private static class AssignableFromPredicate
460 implements Predicate<Class<?>>, Serializable {
461 private final Class<?> clazz;
462
463 private AssignableFromPredicate(Class<?> clazz) {
464 this.clazz = checkNotNull(clazz);
465 }
466 @Override
467 public boolean apply(Class<?> input) {
468 return clazz.isAssignableFrom(input);
469 }
470 @Override public int hashCode() {
471 return clazz.hashCode();
472 }
473 @Override public boolean equals(@Nullable Object obj) {
474 if (obj instanceof AssignableFromPredicate) {
475 AssignableFromPredicate that = (AssignableFromPredicate) obj;
476 return clazz == that.clazz;
477 }
478 return false;
479 }
480 @Override public String toString() {
481 return "IsAssignableFrom(" + clazz.getName() + ")";
482 }
483 private static final long serialVersionUID = 0;
484 }
485
486 /** @see Predicates#in(Collection) */
487 private static class InPredicate<T> implements Predicate<T>, Serializable {
488 private final Collection<?> target;
489
490 private InPredicate(Collection<?> target) {
491 this.target = checkNotNull(target);
492 }
493
494 @Override
495 public boolean apply(T t) {
496 try {
497 return target.contains(t);
498 } catch (NullPointerException e) {
499 return false;
500 } catch (ClassCastException e) {
501 return false;
502 }
503 }
504
505 @Override public boolean equals(@Nullable Object obj) {
506 if (obj instanceof InPredicate) {
507 InPredicate<?> that = (InPredicate<?>) obj;
508 return target.equals(that.target);
509 }
510 return false;
511 }
512
513 @Override public int hashCode() {
514 return target.hashCode();
515 }
516
517 @Override public String toString() {
518 return "In(" + target + ")";
519 }
520 private static final long serialVersionUID = 0;
521 }
522
523 /** @see Predicates#compose(Predicate, Function) */
524 private static class CompositionPredicate<A, B>
525 implements Predicate<A>, Serializable {
526 final Predicate<B> p;
527 final Function<A, ? extends B> f;
528
529 private CompositionPredicate(Predicate<B> p, Function<A, ? extends B> f) {
530 this.p = checkNotNull(p);
531 this.f = checkNotNull(f);
532 }
533
534 @Override
535 public boolean apply(A a) {
536 return p.apply(f.apply(a));
537 }
538
539 @Override public boolean equals(@Nullable Object obj) {
540 if (obj instanceof CompositionPredicate) {
541 CompositionPredicate<?, ?> that = (CompositionPredicate<?, ?>) obj;
542 return f.equals(that.f) && p.equals(that.p);
543 }
544 return false;
545 }
546
547 @Override public int hashCode() {
548 return f.hashCode() ^ p.hashCode();
549 }
550
551 @Override public String toString() {
552 return p.toString() + "(" + f.toString() + ")";
553 }
554
555 private static final long serialVersionUID = 0;
556 }
557
558 /**
559 * @see Predicates#contains(Pattern)
560 * @see Predicates#containsPattern(String)
561 */
562 @GwtIncompatible("Only used by other GWT-incompatible code.")
563 private static class ContainsPatternPredicate
564 implements Predicate<CharSequence>, Serializable {
565 final Pattern pattern;
566
567 ContainsPatternPredicate(Pattern pattern) {
568 this.pattern = checkNotNull(pattern);
569 }
570
571 ContainsPatternPredicate(String patternStr) {
572 this(Pattern.compile(patternStr));
573 }
574
575 @Override
576 public boolean apply(CharSequence t) {
577 return pattern.matcher(t).find();
578 }
579
580 @Override public int hashCode() {
581 // Pattern uses Object.hashCode, so we have to reach
582 // inside to build a hashCode consistent with equals.
583
584 return Objects.hashCode(pattern.pattern(), pattern.flags());
585 }
586
587 @Override public boolean equals(@Nullable Object obj) {
588 if (obj instanceof ContainsPatternPredicate) {
589 ContainsPatternPredicate that = (ContainsPatternPredicate) obj;
590
591 // Pattern uses Object (identity) equality, so we have to reach
592 // inside to compare individual fields.
593 return Objects.equal(pattern.pattern(), that.pattern.pattern())
594 && Objects.equal(pattern.flags(), that.pattern.flags());
595 }
596 return false;
597 }
598
599 @Override public String toString() {
600 return Objects.toStringHelper(this)
601 .add("pattern", pattern)
602 .add("pattern.flags", Integer.toHexString(pattern.flags()))
603 .toString();
604 }
605
606 private static final long serialVersionUID = 0;
607 }
608
609 @SuppressWarnings("unchecked")
610 private static <T> List<Predicate<? super T>> asList(
611 Predicate<? super T> first, Predicate<? super T> second) {
612 return Arrays.<Predicate<? super T>>asList(first, second);
613 }
614
615 private static <T> List<T> defensiveCopy(T... array) {
616 return defensiveCopy(Arrays.asList(array));
617 }
618
619 static <T> List<T> defensiveCopy(Iterable<T> iterable) {
620 ArrayList<T> list = new ArrayList<T>();
621 for (T element : iterable) {
622 list.add(checkNotNull(element));
623 }
624 return list;
625 }
626 }