1 /*
2 * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.util.functions;
26
27 import java.lang.reflect.Array;
28 import java.util.ArrayList;
29 import java.util.Arrays;
30 import java.util.Collection;
31 import java.util.List;
32 import java.util.Objects;
33
34 /**
35 * Static utility methods pertaining to {@code Predicate} instances.
36 *
37 * <p>All of the returned predicates are serializable if given serializable
38 * parameters.
39 */
40 public final class Predicates {
41
42 /**
43 * a predicate that evaluates to {@code true} if the reference
44 * being tested is {@code null}.
45 */
46 public static final Predicate<Object> IS_NULL = #{Object t -> t == null};
47
48 /**
49 * a predicate that evaluates to {@code true} if the reference
50 * being tested is not {@code null}.
51 */
52 public static final Predicate<Object> NON_NULL = #{Object t -> t != null};
53
54 /**
55 * a predicate who's result is always {@code false}.
56 */
57 public static final Predicate<Object> FALSE = #{Object t -> false};
58
59
60 /**
61 * a predicate who's result is always {@code true}.
62 */
63 public static final Predicate<Object> TRUE = #{Object t -> true};
64
65 /**
66 * singleton utils
67 */
68 private Predicates() {
69 throw new AssertionError("No instances!");
70 }
71
72 /**
73 * Returns a predicate that evaluates to {@code true} if the reference
74 * being tested is {@code null}.
75 *
76 * @return a predicate that evaluates to {@code true} if the reference
77 * being tested is {@code null}
78 */
79 public static <T> Predicate<T> isNull() {
80 return (Predicate<T>) IS_NULL;
81 }
82
83 /**
84 * Returns a predicate that evaluates to {@code true} if the reference
85 * being tested is non-{@code null}.
86 *
87 * @return a predicate that evaluates to {@code true} if the reference
88 * being tested is is non-{@code null}
89 */
90 public static <T> Predicate<T> nonNull() {
91 return (Predicate<T>) NON_NULL;
92 }
93
94 /**
95 * Returns a predicate who's result is always {@code false}.
96 *
97 * @return a predicate who's result is always {@code false}.
98 */
99 public static <T> Predicate<T> alwaysFalse() {
100 return (Predicate<T>) FALSE;
101 }
102
103 /**
104 * Returns a predicate who's result is always {@code true}.
105 *
106 * @return a predicate who's result is always {@code true}.
107 */
108 public static <T> Predicate<T> alwaysTrue() {
109 return (Predicate<T>) TRUE;
110 }
111
112 /**
113 * Returns a predicate that evaluates to {@code true} if the object being
114 * tested is an instance of the provided class. If the object being tested
115 * is {@code null} this predicate evaluates to {@code false}.
116 *
117 * @param clazz The target class to be matched by the predicate.
118 * @return a predicate that evaluates to {@code true} if the object being
119 * tested is an instance of the provided class
120 */
121 public static Predicate<Object> instanceOf(Class<?> clazz) {
122 return #{Object o -> clazz.isInstance(o)};
123 }
124
125 /**
126 * Returns a predicate that who's result is {@code target == object}.
127 *
128 * @param <T> the type of predicate values.
129 * @param t The target value to be compared for identity equality.
130 * @return a predicate that who's result is {@code target == object}
131 */
132 public static <T> Predicate<T> isSame(T target) {
133 return #{T t -> t == target};
134 }
135
136 /**
137 * Returns a predicate who's result matches
138 * {@code Objects.equals(target, t)}.
139 *
140 * @param <T> the type of predicate values.
141 * @param t The target value to be compared for equality.
142 * @return a predicate who's result matches {@code Objects.equals(target, t)}
143 */
144 public static <T> Predicate<T> isEqual(T target) {
145 if (null == target)
146 return Predicates.<T>isNull();
147 else
148 return #{T t -> target.equals(t)};
149 }
150
151 /**
152 * Creates a predicate that evaluates to {@code true} if the tested object
153 * is a member of the provided collection. The collection is not defensively
154 * copied so changes to it will alter the behavior of the predicate.
155 *
156 * @param <T> Type of predicate values.
157 * @param target the collection against which objects will be tested.
158 * @return a predicate that evaluates to {@code true} if the tested object
159 * is a member of the provided collection. The collection is not defensively
160 * copied so changes to it will alter the behavior of the predicate.
161 */
162 public static <T> Predicate<T> contains(Collection<? extends T> target) {
163 return #{T t -> target.contains(t)};
164 }
165
166 /**
167 * Creates a predicate that is a composition of a mapper and a predicate.
168 * The returned predicate's result is {@code predicate.eval(mapper.map(t))}.
169 *
170 * @return the composition of the provided mapper and predicate
171 */
172 public static <T, V> Predicate<T> compose(
173 Predicate<V> predicate, Mapper<T, ? extends V> mapper) {
174 return #{T t -> predicate.eval(mapper.map(t))};
175 }
176
177 /**
178 * Returns a predicate that evaluates to {@code true} if the provided
179 * predicate evaluates to {@code false}
180 *
181 * @param <T> the type of values evaluated by the predicate.
182 * @param predicate The predicate to be evaluated.
183 * @return A predicate who's result is the logical inverse of the provided
184 * predicate.
185 */
186 public static <T, P extends Predicate<? super T>> Predicate<T> negate(
187 P predicate) {
188 return #{T t -> !predicate.eval(t)};
189 }
190
191 /**
192 * Returns a predicate that evaluates to {@code true} if all of the
193 * component predicates evaluate to {@code true}. The components are
194 * evaluated in order, and evaluation will terminate upon the first
195 * {@code false} predicate.
196 *
197 * @param <T> the type of values evaluated by the predicates.
198 * @param first initial component predicate to be evaluated.
199 * @param second additional component predicate to be evaluated.
200 * @return A predicate who's result is {@code true} iff all component
201 * predicates are {@code true}.
202 */
203 public static <T, P extends Predicate<? super T>> Predicate<T> and(
204 Predicate<T> first, P second) {
205 if((null != first) && (first == second)) {
206 return (Predicate<T>) first;
207 }
208
209 Objects.requireNonNull(first);
210 Objects.requireNonNull(second);
211
212 return #{T t -> first.eval(t) && second.eval(t)};
213 }
214
215 /**
216 * Returns a predicate that evaluates to {@code true} if all of the
217 * component predicates evaluate to {@code true}. The components are
218 * evaluated in order, and evaluation will end upon the first
219 * {@code false} predicate.
220 *
221 * @param <T> the type of values evaluated by the predicates.
222 * @param components The predicates to be evaluated.
223 * @return A predicate who's result is {@code true} iff all component
224 * predicates are {@code true}.
225 */
226 public static <T, P extends Predicate<? super T>> Predicate<T> and(
227 Iterable<P> components) {
228 List<P> predicates = safeCopyOf(components);
229 if(predicates.isEmpty()) {
230 throw new IllegalArgumentException("no predicates");
231 }
232
233 return #{T t ->
234 for(P predicate : predicates) {
235 if(!predicate.eval(t)) {
236 return false;
237 }
238 }
239 return true;};
240 }
241
242 /**
243 * Returns a predicate that evaluates to {@code true} if all of the
244 * component predicates evaluate to {@code true}. The components are
245 * evaluated in order, and evaluation will end upon the first
246 * {@code false} predicate.
247 *
248 * @param <T> the type of values evaluated by the predicates.
249 * @param components The predicates to be evaluated.
250 * @return A predicate who's result is {@code true} iff all component
251 * predicates are {@code true}.
252 */
253 static <T, P extends Predicate<? super T>> Predicate<T> and(
254 P first, Iterable<P> components) {
255 List<P> predicates = safeCopyOf(first, components);
256
257 return #{T t ->
258 for(P predicate : predicates) {
259 if(!predicate.eval(t)) {
260 return false;
261 }
262 }
263 return true;};
264 }
265
266 /**
267 * Returns a predicate that evaluates to {@code true} if all of the
268 * component predicates evaluate to {@code true}. The components are
269 * evaluated in order, and evaluation will end upon the first
270 * {@code false} predicate.
271 *
272 * @param <T> the type of values evaluated by the predicates.
273 * @param components The predicates to be evaluated. A copy is made of the
274 * components.
275 * @return A predicate who's result is {@code true} iff all component
276 * predicates are {@code true}.
277 */
278 @SafeVarargs
279 public static <T, P extends Predicate<? super T>> Predicate<T> and(
280 P... components) {
281 P[] predicates = safeCopyOf(components);
282 if(0 == predicates.length) {
283 throw new IllegalArgumentException("no predicates");
284 }
285
286 return #{T t ->
287 for(P predicate : predicates) {
288 if(!predicate.eval(t)) {
289 return false;
290 }
291 }
292 return true;};
293 }
294 /**
295 * Returns a predicate that evaluates to {@code true} if all of the
296 * component predicates evaluate to {@code true}. The components are
297 * evaluated in order, and evaluation will end upon the first
298 * {@code false} predicate.
299 *
300 * @param <T> the type of values evaluated by the predicates.
301 * @param first first predicate to be evaluated.
302 * @param components The predicates to be evaluated. A copy is made of the
303 * components.
304 * @return A predicate who's result is {@code true} iff all component
305 * predicates are {@code true}.
306 */
307 @SafeVarargs
308 static <T, P extends Predicate<? super T>> Predicate<T> and(
309 P first, P... components) {
310 P[] predicates = safeCopyOf(first, components);
311 if(0 == predicates.length) {
312 throw new IllegalArgumentException("no predicates");
313 }
314
315 return #{T t ->
316 for(P predicate : predicates) {
317 if(!predicate.eval(t)) {
318 return false;
319 }
320 }
321 return true;};
322 }
323
324 /**
325 * Returns a predicate that evaluates to {@code true} if any of the
326 * component predicates evaluate to {@code true}. The components are
327 * evaluated in order, and evaluation will end upon the first
328 * {@code true} predicate.
329 *
330 * @param <T> the type of values evaluated by the predicates.
331 * @param first initial component predicate to be evaluated.
332 * @param second additional component predicate to be evaluated.
333 * @return A predicate who's result is {@code true} if any component
334 * predicate's result is {@code true}.
335 */
336 public static <T, P extends Predicate<? super T>> Predicate<T> or(
337 Predicate<T> first, P second) {
338 if((null != first) && (first == second)) {
339 return first;
340 }
341
342 Objects.requireNonNull(first);
343 Objects.requireNonNull(second);
344
345 return #{T t -> first.eval(t) || second.eval(t)};
346 }
347
348 /**
349 * Returns a predicate that evaluates to {@code true} if any of the
350 * component predicates evaluate to {@code true}. The components are
351 * evaluated in order, and evaluation will end upon the first
352 * {@code true} predicate.
353 *
354 * @param <T> the type of values evaluated by the predicates.
355 * @param components The predicates to be evaluated. A copy is made of the
356 * components.
357 * @return A predicate who's result is {@code true} if any component
358 * predicate's result is {@code true}.
359 */
360 public static <T, P extends Predicate<? super T>> Predicate<T> or(
361 Iterable<P> components) {
362 List<P> predicates = safeCopyOf(components);
363 if(predicates.isEmpty()) {
364 throw new IllegalArgumentException("no predicates");
365 }
366
367 return #{T t ->
368 for(P predicate : predicates) {
369 if(predicate.eval(t)) {
370 return true;
371 }
372 }
373 return false;};
374 }
375
376 /**
377 * Returns a predicate that evaluates to {@code true} if any of the
378 * component predicates evaluate to {@code true}. The components are
379 * evaluated in order, and evaluation will end upon the first
380 * {@code true} predicate.
381 *
382 * @param <T> the type of values evaluated by the predicates.
383 * @param components The predicates to be evaluated. A copy is made of the
384 * components.
385 * @return A predicate who's result is {@code true} if any component
386 * predicate's result is {@code true}.
387 */
388 static <T, P extends Predicate<? super T>> Predicate<T> or(
389 P first, Iterable<P> components) {
390 List<P> predicates = safeCopyOf(first, components);
391
392 return #{T t ->
393 for(P predicate : predicates) {
394 if(predicate.eval(t)) {
395 return true;
396 }
397 }
398 return false;};
399 }
400
401 /**
402 * Returns a predicate that evaluates to {@code true} if any of the
403 * component predicates evaluate to {@code true}. The components are
404 * evaluated in order, and evaluation will terminate upon the first
405 * {@code true} predicate.
406 *
407 * @param <T> the type of values evaluated by the predicates.
408 * @param components The predicates to be evaluated. A copy is made of the
409 * components.
410 * @return A predicate who's result is {@code true} if any component
411 * predicate's result is {@code true}.
412 */
413 @SafeVarargs
414 public static <T, P extends Predicate<? super T>> Predicate<T> or(
415 P... components) {
416 P[] predicates = safeCopyOf(components);
417 if(0 == predicates.length) {
418 throw new IllegalArgumentException("no predicates");
419 }
420
421 return #{T t ->
422 for(P predicate : predicates) {
423 if(predicate.eval(t)) {
424 return true;
425 }
426 }
427 return false;};
428 }
429
430 /**
431 * Returns a predicate that evaluates to {@code true} if any of the
432 * component predicates evaluate to {@code true}. The components are
433 * evaluated in order, and evaluation will terminate upon the first
434 * {@code true} predicate.
435 *
436 * @param <T> the type of values evaluated by the predicates.
437 * @param components The predicates to be evaluated. A copy is made of the
438 * components.
439 * @return A predicate who's result is {@code true} if any component
440 * predicate's result is {@code true}.
441 */
442 @SafeVarargs
443 static <T, P extends Predicate<? super T>> Predicate<T> or(
444 Predicate<T> first, P... components) {
445 P[] predicates = safeCopyOf((P) first, components);
446
447 return #{T t ->
448 for(P predicate : predicates) {
449 if(predicate.eval(t)) {
450 return true;
451 }
452 }
453 return false;};
454 }
455
456 /**
457 * Returns a predicate that evaluates to {@code true} if all or none of the
458 * component predicates evaluate to {@code true}. The components are
459 * evaluated in order, and evaluation will end if a predicate result
460 * fails to match the first predicate's result.
461 *
462 * @param <T> the type of values evaluated by the predicates.
463 * @param first initial component predicate to be evaluated.
464 * @param second additional component predicate to be evaluated.
465 * @return a predicate that evaluates to {@code true} if all or none of the
466 * component predicates evaluate to {@code true}
467 */
468 public static <T, P extends Predicate<? super T>> Predicate<T> xor(
469 Predicate<T> first, P second) {
470 if((null != first) && (first == second)) {
471 return #{T t -> false};
472 }
473
474 Objects.requireNonNull(first);
475 Objects.requireNonNull(second);
476
477 return #{T t -> first.eval(t) ^ second.eval(t)};
478 }
479
480 /**
481 * Returns a predicate that evaluates to {@code false} if all or none of the
482 * component predicates evaluate to {@code true}. The components are
483 * evaluated in order, and evaluation will end if a predicate result
484 * fails to match the first predicate's result.
485 *
486 * @param <T> the type of values evaluated by the predicates.
487 * @param components The predicates to be evaluated. A copy is made of the
488 * components.
489 * @return a predicate that evaluates to {@code false} if all or none of the
490 * component predicates evaluate to {@code true}
491 */
492 public static <T, P extends Predicate<? super T>> Predicate<T> xor(
493 Iterable<P> components) {
494 List<P> predicates = safeCopyOf(components);
495 if(predicates.isEmpty()) {
496 throw new IllegalArgumentException("no predicates");
497 }
498
499 return #{T t ->
500 Boolean initial = null;
501 for (P predicate : predicates) {
502 if (null == initial) {
503 initial = predicate.eval(t);
504 } else {
505 if (!(initial ^ predicate.eval(t))) {
506 return true;
507 }
508 }
509 }
510 return false;};
511 }
512
513 /**
514 * Returns a predicate that evaluates to {@code false} if all or none of the
515 * component predicates evaluate to {@code true}. The components are
516 * evaluated in order, and evaluation will terminate if a predicate result
517 * fails to match the first predicate's result.
518 *
519 * @param <T> the type of values evaluated by the predicates.
520 * @param components The predicates to be evaluated. A copy is made of the
521 * components.
522 * @return a predicate that evaluates to {@code false} if all or none of the
523 * component predicates evaluate to {@code true}
524 */
525 @SafeVarargs
526 public static <T, P extends Predicate<? super T>> Predicate<T> xor(P... components) {
527 P[] predicates = safeCopyOf(components);
528 if(0 == predicates.length) {
529 throw new IllegalArgumentException("no predicates");
530 }
531
532 return #{T t ->
533 Boolean initial = null;
534 for (P predicate : predicates) {
535 if (null == initial) {
536 initial = predicate.eval(t);
537 } else {
538 if (!(initial ^ predicate.eval(t))) {
539 return true;
540 }
541 }
542 }
543 return false;};
544 }
545
546 /**
547 * Returns a predicate that evaluates to {@code false} if all or none of the
548 * component predicates evaluate to {@code true}. The components are
549 * evaluated in order, and evaluation will end if a predicate result
550 * fails to match the first predicate's result.
551 *
552 * @param <T> the type of values evaluated by the predicates.
553 * @param components The predicates to be evaluated. A copy is made of the
554 * components.
555 * @return a predicate that evaluates to {@code false} if all or none of the
556 * component predicates evaluate to {@code true}
557 */
558 @SafeVarargs
559 static <T, P extends Predicate<? super T>> Predicate<T> xor(
560 Predicate<T> first,
561 P... components) {
562 P[] predicates = safeCopyOf((P) first, components);
563
564 return #{T t ->
565 Boolean initial = null;
566 for (P predicate : predicates) {
567 if (null == initial) {
568 initial = predicate.eval(t);
569 } else {
570 if (!(initial ^ predicate.eval(t))) {
571 return true;
572 }
573 }
574 }
575 return false;};
576 }
577
578 /**
579 * Returns a predicate that evaluates to {@code false} if all or none of the
580 * component predicates evaluate to {@code true}. The components are
581 * evaluated in order, and evaluation will end if a predicate result
582 * fails to match the first predicate's result.
583 *
584 * @param <T> the type of values evaluated by the predicates.
585 * @param components The predicates to be evaluated. A copy is made of the
586 * components.
587 * @return a predicate that evaluates to {@code false} if all or none of the
588 * component predicates evaluate to {@code true}
589 */
590 static <T, P extends Predicate<? super T>> Predicate<T> xor(
591 Predicate<T> first,
592 Iterable<P> components) {
593 List<P> predicates = safeCopyOf((P) first, components);
594
595 return #{T t ->
596 Boolean initial = null;
597 for (P predicate : predicates) {
598 if (null == initial) {
599 initial = predicate.eval(t);
600 } else {
601 if (!(initial ^ predicate.eval(t))) {
602 return true;
603 }
604 }
605 }
606 return false;};
607 }
608
609 // XXX mduigou These need to be moved somewhere.
610
611 @SafeVarargs
612 static <T> T[] safeCopyOf(T... array) {
613 T[] copy = Arrays.copyOf(array, array.length);
614 for(T each : copy) {
615 Objects.requireNonNull(each);
616 }
617 return copy;
618 }
619
620 @SafeVarargs
621 static <T> T[] safeCopyOf(T first, T... array) {
622 T[] copy = (T[]) Array.newInstance(array.getClass().getComponentType(), array.length + 1);
623 copy[0] = Objects.requireNonNull(first);
624 System.arraycopy(array, 0, copy, 1, array.length);
625 for(T each : copy) {
626 Objects.requireNonNull(each);
627 }
628 return copy;
629 }
630
631 static <T> List<T> safeCopyOf(T first, Iterable<T> iterable) {
632 ArrayList<T> list = new ArrayList<>();
633 list.add(Objects.requireNonNull(first));
634
635 for (T element : iterable) {
636 list.add(Objects.requireNonNull(element));
637 }
638 return list;
639 }
640
641 static <T> List<T> safeCopyOf(Iterable<T> iterable) {
642 ArrayList<T> list = new ArrayList<>();
643 for (T element : iterable) {
644 list.add(Objects.requireNonNull(element));
645 }
646 return list;
647 }
648 }