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