1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.io.function;
19
20 import java.io.IOException;
21 import java.io.UncheckedIOException;
22 import java.util.Objects;
23 import java.util.function.Predicate;
24
25 /**
26 * Like {@link Predicate} but throws {@link IOException}.
27 *
28 * @param <T> the type of the input to the predicate
29 * @since 2.12.0
30 */
31 @FunctionalInterface
32 public interface IOPredicate<T> {
33
34 /**
35 * Always false.
36 *
37 * @param <T> the type of the input to the predicate
38 * @return a constant predicate that tests always false.
39 */
40 @SuppressWarnings("unchecked")
41 static <T> IOPredicate<T> alwaysFalse() {
42 return (IOPredicate<T>) Constants.IO_PREDICATE_FALSE;
43 }
44
45 /**
46 * Always true.
47 *
48 * @param <T> the type of the input to the predicate
49 * @return a constant predicate that tests always true.
50 */
51 @SuppressWarnings("unchecked")
52 static <T> IOPredicate<T> alwaysTrue() {
53 return (IOPredicate<T>) Constants.IO_PREDICATE_TRUE;
54 }
55
56 /**
57 * Creates a predicate that tests if two arguments are equal using {@link Objects#equals(Object, Object)}.
58 *
59 * @param <T> the type of arguments to the predicate
60 * @param target the object to compare for equality, may be {@code null}
61 * @return a predicate that tests if two arguments are equal using {@link Objects#equals(Object, Object)}
62 */
63 static <T> IOPredicate<T> isEqual(final Object target) {
64 return null == target ? Objects::isNull : object -> target.equals(object);
65 }
66
67 /**
68 * Creates a composed predicate that represents a short-circuiting logical AND of this predicate and another. When
69 * evaluating the composed predicate, if this predicate is {@code false}, then the {@code other} predicate is not
70 * evaluated.
71 *
72 * <p>
73 * Any exceptions thrown during evaluation of either predicate are relayed to the caller; if evaluation of this
74 * predicate throws an exception, the {@code other} predicate will not be evaluated.
75 * </p>
76 *
77 * @param other a predicate that will be logically-ANDed with this predicate
78 * @return a composed predicate that represents the short-circuiting logical AND of this predicate and the {@code other}
79 * predicate
80 * @throws NullPointerException if other is null
81 */
82 default IOPredicate<T> and(final IOPredicate<? super T> other) {
83 Objects.requireNonNull(other);
84 return t -> test(t) && other.test(t);
85 }
86
87 /**
88 * Creates a {@link Predicate} for this instance that throws {@link UncheckedIOException} instead of
89 * {@link IOException}.
90 *
91 * @return an UncheckedIOException Predicate.
92 */
93 default Predicate<T> asPredicate() {
94 return t -> Uncheck.test(this, t);
95 }
96
97 /**
98 * Creates a predicate that represents the logical negation of this predicate.
99 *
100 * @return a predicate that represents the logical negation of this predicate
101 */
102 default IOPredicate<T> negate() {
103 return t -> !test(t);
104 }
105
106 /**
107 * Creates a composed predicate that represents a short-circuiting logical OR of this predicate and another. When
108 * evaluating the composed predicate, if this predicate is {@code true}, then the {@code other} predicate is not
109 * evaluated.
110 *
111 * <p>
112 * Any exceptions thrown during evaluation of either predicate are relayed to the caller; if evaluation of this
113 * predicate throws an exception, the {@code other} predicate will not be evaluated.
114 * </p>
115 *
116 * @param other a predicate that will be logically-ORed with this predicate
117 * @return a composed predicate that represents the short-circuiting logical OR of this predicate and the {@code other}
118 * predicate
119 * @throws NullPointerException if other is null
120 */
121 default IOPredicate<T> or(final IOPredicate<? super T> other) {
122 Objects.requireNonNull(other);
123 return t -> test(t) || other.test(t);
124 }
125
126 /**
127 * Evaluates this predicate on the given argument.
128 *
129 * @param t the input argument
130 * @return {@code true} if the input argument matches the predicate, otherwise {@code false}
131 * @throws IOException if an I/O error occurs.
132 */
133 boolean test(T t) throws IOException;
134
135 }