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") alwaysFalse()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") alwaysTrue()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 */ isEqual(final Object target)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 */ and(final IOPredicate<? super T> other)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 */ asPredicate()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 */ negate()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 */ or(final IOPredicate<? super T> other)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 */ test(T t)133 boolean test(T t) throws IOException; 134 135 } 136