[LANG-1568] Predicate negation.

13 files changed, 234 insertions, 32 deletions

diff --git a/src/main/java/org/apache/commons/lang3/function/Failable.java b/src/main/java/org/apache/commons/lang3/function/Failable.java
index 7ff69bdb4..d2a12a07d 100644
--- a/src/main/java/org/apache/commons/lang3/function/Failable.java
+++ b/src/main/java/org/apache/commons/lang3/function/Failable.java
@@ -41,7 +41,8 @@ import org.apache.commons.lang3.stream.Streams.FailableStream;
  * constructs like:
  *
  * <pre>
- * {@code
+ * {
+ *     &#64;code
  *     Consumer<java.lang.reflect.Method> consumer = (m) -> {
  *         try {
  *             m.invoke(o, args);
@@ -49,7 +50,8 @@ import org.apache.commons.lang3.stream.Streams.FailableStream;
  *             throw Failable.rethrow(t);
  *         }
  *     };
- * }</pre>
+ * }
+ * </pre>
  *
  * <p>
  * By replacing a {@link java.util.function.Consumer Consumer&lt;O&gt;} with a {@link FailableConsumer
@@ -59,7 +61,8 @@ import org.apache.commons.lang3.stream.Streams.FailableStream;
  * <pre>
  * {@code
  *   Functions.accept((m) -> m.invoke(o,args));
- * }</pre>
+ * }
+ * </pre>
  *
  * <p>
  * Obviously, the second version is much more concise and the spirit of Lambda expressions is met better than the second
@@ -80,8 +83,8 @@ public class Failable {
      * @param <U> the type of the second argument the consumer accepts
      * @param <E> the type of checked exception the consumer may throw
      */
-    public static <T, U, E extends Throwable> void accept(final FailableBiConsumer<T, U, E> consumer,
-        final T object1, final U object2) {
+    public static <T, U, E extends Throwable> void accept(final FailableBiConsumer<T, U, E> consumer, final T object1,
+        final U object2) {
         run(() -> consumer.accept(object1, object2));
     }
 
@@ -142,8 +145,8 @@ public class Failable {
      * @param <E> the type of checked exception the function may throw
      * @return the value returned from the function
      */
-    public static <T, U, R, E extends Throwable> R apply(final FailableBiFunction<T, U, R, E> function,
-        final T input1, final U input2) {
+    public static <T, U, R, E extends Throwable> R apply(final FailableBiFunction<T, U, R, E> function, final T input1,
+        final U input2) {
         return get(() -> function.apply(input1, input2));
     }
 
@@ -487,7 +490,8 @@ public class Failable {
      * {@link Throwable} is rethrown. Example use:
      *
      * <pre>
-     *     {@code
+     * {
+     *     &#64;code
      *     final FileInputStream fis = new FileInputStream("my.file");
      *     Functions.tryWithResources(useInputStream(fis), null, () -> fis.close());
      * }
@@ -549,7 +553,8 @@ public class Failable {
      * {@link Throwable} is rethrown. Example use:
      *
      * <pre>
-     *     {@code
+     * {
+     *     &#64;code
      *     final FileInputStream fis = new FileInputStream("my.file");
      *     Functions.tryWithResources(useInputStream(fis), () -> fis.close());
      * }
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableBiFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableBiFunction.java
index 15d1788f3..f7d633943 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableBiFunction.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableBiFunction.java
@@ -59,7 +59,8 @@ public interface FailableBiFunction<T, U, R, E extends Throwable> {
      * @throws NullPointerException when {@code after} is null.
      * @throws E Thrown when a consumer fails.
      */
-    default <V> FailableBiFunction<T, U, V, E> andThen(final FailableFunction<? super R, ? extends V, E> after) throws E {
+    default <V> FailableBiFunction<T, U, V, E> andThen(final FailableFunction<? super R, ? extends V, E> after)
+        throws E {
         Objects.requireNonNull(after);
         return (final T t, final U u) -> after.apply(apply(t, u));
     }
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableBiPredicate.java b/src/main/java/org/apache/commons/lang3/function/FailableBiPredicate.java
index 22993572a..75936c9e2 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableBiPredicate.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableBiPredicate.java
@@ -30,13 +30,55 @@ import java.util.function.BiPredicate;
 @FunctionalInterface
 public interface FailableBiPredicate<T, U, E extends Throwable> {
 
+    /** FALSE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableBiPredicate FALSE = (t, u) -> false;
+
+    /** TRUE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableBiPredicate TRUE = (t, u) -> true;
+
+    /**
+     * Returns The FALSE singleton.
+     *
+     * @param <T> Consumed type 1.
+     * @param <U> Consumed type 2.
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <T, U, E extends Throwable> FailableBiPredicate<T, U, E> falsePredicate() {
+        return FALSE;
+    }
+
+    /**
+     * Returns The FALSE TRUE.
+     *
+     * @param <T> Consumed type 1.
+     * @param <U> Consumed type 2.
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <T, U, E extends Throwable> FailableBiPredicate<T, U, E> truePredicate() {
+        return TRUE;
+    }
+
+    /**
+     * Returns a predicate that negates this predicate.
+     *
+     * @return a predicate that negates this predicate.
+     * @throws E Thrown when this predicate fails.
+     */
+    default FailableBiPredicate<T, U, E> negate() throws E {
+        return (final T t, final U u) -> !test(t, u);
+    }
+
     /**
      * Tests the predicate.
      *
      * @param object1 the first object to test the predicate on
      * @param object2 the second object to test the predicate on
      * @return the predicate's evaluation
-     * @throws E if the predicate fails
+     * @throws E Thrown when this predicate fails.
      */
     boolean test(T object1, U object2) throws E;
 }
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoublePredicate.java b/src/main/java/org/apache/commons/lang3/function/FailableDoublePredicate.java
index abdd2cb7e..db3fdacdd 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableDoublePredicate.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableDoublePredicate.java
@@ -28,6 +28,44 @@ import java.util.function.DoublePredicate;
 @FunctionalInterface
 public interface FailableDoublePredicate<E extends Throwable> {
 
+    /** FALSE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableDoublePredicate FALSE = t -> false;
+
+    /** TRUE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableDoublePredicate TRUE = t -> true;
+
+    /**
+     * Returns The FALSE singleton.
+     *
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <E extends Throwable> FailableDoublePredicate<E> falsePredicate() {
+        return FALSE;
+    }
+
+    /**
+     * Returns The FALSE TRUE.
+     *
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <E extends Throwable> FailableDoublePredicate<E> truePredicate() {
+        return TRUE;
+    }
+
+    /**
+     * Returns a predicate that negates this predicate.
+     *
+     * @return a predicate that negates this predicate.
+     * @throws E Thrown when this predicate fails.
+     */
+    default FailableDoublePredicate<E> negate() throws E {
+        return t -> !test(t);
+    }
+
     /**
      * Tests the predicate.
      *
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleUnaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleUnaryOperator.java
index 3fa2738f6..2674f1d86 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableDoubleUnaryOperator.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleUnaryOperator.java
@@ -63,9 +63,9 @@ public interface FailableDoubleUnaryOperator<E extends Throwable> {
      * @throws E Thrown when a consumer fails.
      * @see #compose(FailableDoubleUnaryOperator)
      */
-    default FailableDoubleUnaryOperator<E> andThen(FailableDoubleUnaryOperator<E> after) throws E {
+    default FailableDoubleUnaryOperator<E> andThen(final FailableDoubleUnaryOperator<E> after) throws E {
         Objects.requireNonNull(after);
-        return (double t) -> after.applyAsDouble(applyAsDouble(t));
+        return (final double t) -> after.applyAsDouble(applyAsDouble(t));
     }
 
     /**
@@ -88,8 +88,8 @@ public interface FailableDoubleUnaryOperator<E extends Throwable> {
      * @throws E Thrown when a consumer fails.
      * @see #andThen(FailableDoubleUnaryOperator)
      */
-    default FailableDoubleUnaryOperator<E> compose(FailableDoubleUnaryOperator<E> before) throws E {
+    default FailableDoubleUnaryOperator<E> compose(final FailableDoubleUnaryOperator<E> before) throws E {
         Objects.requireNonNull(before);
-        return (double v) -> applyAsDouble(before.applyAsDouble(v));
+        return (final double v) -> applyAsDouble(before.applyAsDouble(v));
     }
 }
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntPredicate.java b/src/main/java/org/apache/commons/lang3/function/FailableIntPredicate.java
index 837ba319c..12bd5c0cc 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableIntPredicate.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableIntPredicate.java
@@ -28,6 +28,44 @@ import java.util.function.IntPredicate;
 @FunctionalInterface
 public interface FailableIntPredicate<E extends Throwable> {
 
+    /** FALSE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableIntPredicate FALSE = t -> false;
+
+    /** TRUE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableIntPredicate TRUE = t -> true;
+
+    /**
+     * Returns The FALSE singleton.
+     *
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <E extends Throwable> FailableIntPredicate<E> falsePredicate() {
+        return FALSE;
+    }
+
+    /**
+     * Returns The FALSE TRUE.
+     *
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <E extends Throwable> FailableIntPredicate<E> truePredicate() {
+        return TRUE;
+    }
+
+    /**
+     * Returns a predicate that negates this predicate.
+     *
+     * @return a predicate that negates this predicate.
+     * @throws E Thrown when this predicate fails.
+     */
+    default FailableIntPredicate<E> negate() throws E {
+        return t -> !test(t);
+    }
+
     /**
      * Tests the predicate.
      *
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntUnaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableIntUnaryOperator.java
index 9b6e1eb93..b685885d9 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableIntUnaryOperator.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableIntUnaryOperator.java
@@ -61,9 +61,9 @@ public interface FailableIntUnaryOperator<E extends Throwable> {
      * @throws E Thrown when a consumer fails.
      * @see #compose(FailableIntUnaryOperator)
      */
-    default FailableIntUnaryOperator<E> andThen(FailableIntUnaryOperator<E> after) throws E {
+    default FailableIntUnaryOperator<E> andThen(final FailableIntUnaryOperator<E> after) throws E {
         Objects.requireNonNull(after);
-        return (int t) -> after.applyAsInt(applyAsInt(t));
+        return (final int t) -> after.applyAsInt(applyAsInt(t));
     }
 
     /**
@@ -84,8 +84,8 @@ public interface FailableIntUnaryOperator<E extends Throwable> {
      * @throws E Thrown when a consumer fails.
      * @see #andThen(FailableIntUnaryOperator)
      */
-    default FailableIntUnaryOperator<E> compose(FailableIntUnaryOperator<E> before) throws E {
+    default FailableIntUnaryOperator<E> compose(final FailableIntUnaryOperator<E> before) throws E {
         Objects.requireNonNull(before);
-        return (int v) -> applyAsInt(before.applyAsInt(v));
+        return (final int v) -> applyAsInt(before.applyAsInt(v));
     }
 }
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongPredicate.java b/src/main/java/org/apache/commons/lang3/function/FailableLongPredicate.java
index 3c756ca97..b267ead67 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableLongPredicate.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableLongPredicate.java
@@ -28,6 +28,44 @@ import java.util.function.LongPredicate;
 @FunctionalInterface
 public interface FailableLongPredicate<E extends Throwable> {
 
+    /** FALSE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableLongPredicate FALSE = t -> false;
+
+    /** TRUE singleton */
+    @SuppressWarnings("rawtypes")
+    FailableLongPredicate TRUE = t -> true;
+
+    /**
+     * Returns The FALSE singleton.
+     *
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <E extends Throwable> FailableLongPredicate<E> falsePredicate() {
+        return FALSE;
+    }
+
+    /**
+     * Returns The FALSE TRUE.
+     *
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <E extends Throwable> FailableLongPredicate<E> truePredicate() {
+        return TRUE;
+    }
+
+    /**
+     * Returns a predicate that negates this predicate.
+     *
+     * @return a predicate that negates this predicate.
+     * @throws E Thrown when this predicate fails.
+     */
+    default FailableLongPredicate<E> negate() throws E {
+        return t -> !test(t);
+    }
+
     /**
      * Tests the predicate.
      *
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongUnaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableLongUnaryOperator.java
index 9543ded77..6f980b765 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableLongUnaryOperator.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableLongUnaryOperator.java
@@ -61,9 +61,9 @@ public interface FailableLongUnaryOperator<E extends Throwable> {
      * @throws E Thrown when a consumer fails.
      * @see #compose(FailableLongUnaryOperator)
      */
-    default FailableLongUnaryOperator<E> andThen(FailableLongUnaryOperator<E> after) throws E {
+    default FailableLongUnaryOperator<E> andThen(final FailableLongUnaryOperator<E> after) throws E {
         Objects.requireNonNull(after);
-        return (long t) -> after.applyAsLong(applyAsLong(t));
+        return (final long t) -> after.applyAsLong(applyAsLong(t));
     }
 
     /**
@@ -84,8 +84,8 @@ public interface FailableLongUnaryOperator<E extends Throwable> {
      * @throws E Thrown when a consumer fails.
      * @see #andThen(FailableLongUnaryOperator)
      */
-    default FailableLongUnaryOperator<E> compose(FailableLongUnaryOperator<E> before) throws E {
+    default FailableLongUnaryOperator<E> compose(final FailableLongUnaryOperator<E> before) throws E {
         Objects.requireNonNull(before);
-        return (long v) -> applyAsLong(before.applyAsLong(v));
+        return (final long v) -> applyAsLong(before.applyAsLong(v));
     }
 }
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableObjIntConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableObjIntConsumer.java
index baa99b0b9..483f0f4b3 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableObjIntConsumer.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableObjIntConsumer.java
@@ -48,7 +48,7 @@ public interface FailableObjIntConsumer<T, E extends Throwable> {
      * Accepts the consumer.
      *
      * @param object the object parameter for the consumable to accept.
-     * @param value  the int parameter for the consumable to accept.
+     * @param value the int parameter for the consumable to accept.
      * @throws E Thrown when the consumer fails.
      */
     void accept(T object, int value) throws E;
diff --git a/src/main/java/org/apache/commons/lang3/function/FailableObjLongConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableObjLongConsumer.java
index 59790453c..378ff0f64 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailableObjLongConsumer.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailableObjLongConsumer.java
@@ -48,7 +48,7 @@ public interface FailableObjLongConsumer<T, E extends Throwable> {
      * Accepts the consumer.
      *
      * @param object the object parameter for the consumable to accept.
-     * @param value  the long parameter for the consumable to accept.
+     * @param value the long parameter for the consumable to accept.
      * @throws E Thrown when the consumer fails.
      */
     void accept(T object, long value) throws E;
diff --git a/src/main/java/org/apache/commons/lang3/function/FailablePredicate.java b/src/main/java/org/apache/commons/lang3/function/FailablePredicate.java
index 999107a15..ce49539b9 100644
--- a/src/main/java/org/apache/commons/lang3/function/FailablePredicate.java
+++ b/src/main/java/org/apache/commons/lang3/function/FailablePredicate.java
@@ -22,13 +22,53 @@ import java.util.function.Predicate;
 /**
  * A functional interface like {@link Predicate} that declares a {@code Throwable}.
  *
- * @param <T> Predicate type 1.
+ * @param <T> Predicate type.
  * @param <E> Thrown exception.
  * @since 3.11
  */
 @FunctionalInterface
 public interface FailablePredicate<T, E extends Throwable> {
 
+    /** FALSE singleton */
+    @SuppressWarnings("rawtypes")
+    FailablePredicate FALSE = t -> false;
+
+    /** TRUE singleton */
+    @SuppressWarnings("rawtypes")
+    FailablePredicate TRUE = t -> true;
+
+    /**
+     * Returns The FALSE singleton.
+     *
+     * @param <T> Predicate type.
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <T, E extends Throwable> FailablePredicate<T, E> falsePredicate() {
+        return FALSE;
+    }
+
+    /**
+     * Returns The FALSE TRUE.
+     *
+     * @param <T> Predicate type.
+     * @param <E> Thrown exception.
+     * @return The NOP singleton.
+     */
+    static <T, E extends Throwable> FailablePredicate<T, E> truePredicate() {
+        return TRUE;
+    }
+
+    /**
+     * Returns a predicate that negates this predicate.
+     *
+     * @return a predicate that negates this predicate.
+     * @throws E Thrown when this predicate fails.
+     */
+    default FailablePredicate<T, E> negate() throws E {
+        return t -> !test(t);
+    }
+
     /**
      * Tests the predicate.
      *
diff --git a/src/main/java/org/apache/commons/lang3/function/package-info.java b/src/main/java/org/apache/commons/lang3/function/package-info.java
index 5cc1d9a63..4a0ccd913 100644
--- a/src/main/java/org/apache/commons/lang3/function/package-info.java
+++ b/src/main/java/org/apache/commons/lang3/function/package-info.java
@@ -15,13 +15,13 @@
  * limitations under the License.
  */
 /**
- * Provides functional interfaces to complement those in {@code java.lang.function} and utilities
- * for working with Java 8 lambdas.
+ * Provides functional interfaces to complement those in {@code java.lang.function} and utilities for working with Java
+ * 8 lambdas.
  *
- * <p>Contains failable functional interfaces that address the fact that lambdas are supposed not to
- * throw Exceptions, at least not checked Exceptions, A.K.A. instances of {@link java.lang.Exception}.
- * A failable functional interface declares a type of Exception that may be raised if the function
- * fails.
+ * <p>
+ * Contains failable functional interfaces that address the fact that lambdas are supposed not to throw Exceptions, at
+ * least not checked Exceptions, A.K.A. instances of {@link java.lang.Exception}. A failable functional interface
+ * declares a type of Exception that may be raised if the function fails.
  *
  * @since 3.11
  */