001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.base; 016 017import static com.google.common.base.Preconditions.checkNotNull; 018 019import com.google.common.annotations.Beta; 020import com.google.common.annotations.GwtCompatible; 021import com.google.common.annotations.GwtIncompatible; 022import java.io.Serializable; 023import java.util.ArrayList; 024import java.util.Arrays; 025import java.util.Collection; 026import java.util.List; 027import java.util.regex.Pattern; 028import org.checkerframework.checker.nullness.qual.Nullable; 029 030/** 031 * Static utility methods pertaining to {@code Predicate} instances. 032 * 033 * <p>All methods return serializable predicates as long as they're given serializable parameters. 034 * 035 * <p>See the Guava User Guide article on <a 036 * href="https://github.com/google/guava/wiki/FunctionalExplained">the use of {@code Predicate}</a>. 037 * 038 * @author Kevin Bourrillion 039 * @since 2.0 040 */ 041@GwtCompatible(emulated = true) 042public final class Predicates { 043 private Predicates() {} 044 045 // TODO(kevinb): considering having these implement a VisitablePredicate 046 // interface which specifies an accept(PredicateVisitor) method. 047 048 /** Returns a predicate that always evaluates to {@code true}. */ 049 @GwtCompatible(serializable = true) 050 public static <T> Predicate<T> alwaysTrue() { 051 return ObjectPredicate.ALWAYS_TRUE.withNarrowedType(); 052 } 053 054 /** Returns a predicate that always evaluates to {@code false}. */ 055 @GwtCompatible(serializable = true) 056 public static <T> Predicate<T> alwaysFalse() { 057 return ObjectPredicate.ALWAYS_FALSE.withNarrowedType(); 058 } 059 060 /** 061 * Returns a predicate that evaluates to {@code true} if the object reference being tested is 062 * null. 063 */ 064 @GwtCompatible(serializable = true) 065 public static <T> Predicate<T> isNull() { 066 return ObjectPredicate.IS_NULL.withNarrowedType(); 067 } 068 069 /** 070 * Returns a predicate that evaluates to {@code true} if the object reference being tested is not 071 * null. 072 */ 073 @GwtCompatible(serializable = true) 074 public static <T> Predicate<T> notNull() { 075 return ObjectPredicate.NOT_NULL.withNarrowedType(); 076 } 077 078 /** 079 * Returns a predicate that evaluates to {@code true} if the given predicate evaluates to {@code 080 * false}. 081 */ 082 public static <T> Predicate<T> not(Predicate<T> predicate) { 083 return new NotPredicate<T>(predicate); 084 } 085 086 /** 087 * Returns a predicate that evaluates to {@code true} if each of its components evaluates to 088 * {@code true}. The components are evaluated in order, and evaluation will be "short-circuited" 089 * as soon as a false predicate is found. It defensively copies the iterable passed in, so future 090 * changes to it won't alter the behavior of this predicate. If {@code components} is empty, the 091 * returned predicate will always evaluate to {@code true}. 092 */ 093 public static <T> Predicate<T> and(Iterable<? extends Predicate<? super T>> components) { 094 return new AndPredicate<T>(defensiveCopy(components)); 095 } 096 097 /** 098 * Returns a predicate that evaluates to {@code true} if each of its components evaluates to 099 * {@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 Predicate<Object> instanceOf(Class<?> clazz) { 173 return new InstanceOfPredicate(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 implements Predicate<Object>, 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 Object 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}