diff options
Diffstat (limited to 'src/main/java/org/apache/commons/lang3/function')
54 files changed, 3965 insertions, 0 deletions
diff --git a/src/main/java/org/apache/commons/lang3/function/BooleanConsumer.java b/src/main/java/org/apache/commons/lang3/function/BooleanConsumer.java new file mode 100644 index 000000000..9a6147241 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/BooleanConsumer.java @@ -0,0 +1,68 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.IntConsumer; + +/** + * A functional interface like {@link IntConsumer} but for {@code boolean}. + * + * @see IntConsumer + * @since 3.13.0 + */ +@FunctionalInterface +public interface BooleanConsumer { + + /** NOP singleton */ + BooleanConsumer NOP = t -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @return The NOP singleton. + */ + static BooleanConsumer nop() { + return NOP; + } + + /** + * Performs this operation on the given argument. + * + * @param value the input argument + */ + void accept(boolean value); + + /** + * Returns a composed {@link BooleanConsumer} that performs, in sequence, this operation followed by the {@code after} + * operation. If performing either operation throws an exception, it is relayed to the caller of the composed operation. + * If performing this operation throws an exception, the {@code after} operation will not be performed. + * + * @param after the operation to perform after this operation + * @return a composed {@link BooleanConsumer} that performs in sequence this operation followed by the {@code after} + * operation + * @throws NullPointerException if {@code after} is null + */ + default BooleanConsumer andThen(final BooleanConsumer after) { + Objects.requireNonNull(after); + return (final boolean t) -> { + accept(t); + after.accept(t); + }; + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/Consumers.java b/src/main/java/org/apache/commons/lang3/function/Consumers.java new file mode 100644 index 000000000..19b5efd9e --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/Consumers.java @@ -0,0 +1,49 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.Consumer; +import java.util.function.Function; + +/** + * Provides {@link Consumer} instances. + * + * @since 3.13.0 + */ +public class Consumers { + + /** NOP singleton. */ + @SuppressWarnings("rawtypes") + private static final Consumer NOP = Function.identity()::apply; + + private Consumers() { + // No instances. + } + + /** + * Gets the NOP Consumer singleton. + * + * @param <T> type type to consume. + * @return the NOP Consumer singleton.. + */ + @SuppressWarnings("unchecked") + public static <T> Consumer<T> nop() { + return NOP; + } + +} diff --git a/src/main/java/org/apache/commons/lang3/function/Failable.java b/src/main/java/org/apache/commons/lang3/function/Failable.java new file mode 100644 index 000000000..efe3f707a --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/Failable.java @@ -0,0 +1,578 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.io.IOException; +import java.io.UncheckedIOException; +import java.lang.reflect.UndeclaredThrowableException; +import java.util.Collection; +import java.util.Objects; +import java.util.concurrent.Callable; +import java.util.function.BiConsumer; +import java.util.function.BiFunction; +import java.util.function.BiPredicate; +import java.util.function.Consumer; +import java.util.function.Function; +import java.util.function.Predicate; +import java.util.function.Supplier; +import java.util.stream.Stream; + +import org.apache.commons.lang3.stream.Streams; +import org.apache.commons.lang3.stream.Streams.FailableStream; + +/** + * This class provides utility functions, and classes for working with the {@code java.util.function} package, or more + * generally, with Java 8 lambdas. More specifically, it attempts to address the fact that lambdas are supposed not to + * throw Exceptions, at least not checked Exceptions, AKA instances of {@link Exception}. This enforces the use of + * constructs like: + * + * <pre> + * Consumer<java.lang.reflect.Method-> consumer = m -> { + * try { + * m.invoke(o, args); + * } catch (Throwable t) { + * throw Failable.rethrow(t); + * } + * }; + * </pre> + * + * <p> + * By replacing a {@link java.util.function.Consumer Consumer<O>} with a {@link FailableConsumer + * FailableConsumer<O,? extends Throwable>}, this can be written like follows: + * </p> + * + * <pre> + * Functions.accept((m) -> m.invoke(o, args)); + * </pre> + * + * <p> + * Obviously, the second version is much more concise and the spirit of Lambda expressions is met better than the second + * version. + * </p> + * + * @since 3.11 + */ +public class Failable { + + /** + * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. + * + * @param consumer the consumer to consume + * @param object1 the first object to consume by {@code consumer} + * @param object2 the second object to consume by {@code consumer} + * @param <T> the type of the first argument the consumer accepts + * @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) { + run(() -> consumer.accept(object1, object2)); + } + + /** + * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. + * + * @param consumer the consumer to consume + * @param object the object to consume by {@code consumer} + * @param <T> the type the consumer accepts + * @param <E> the type of checked exception the consumer may throw + */ + public static <T, E extends Throwable> void accept(final FailableConsumer<T, E> consumer, final T object) { + run(() -> consumer.accept(object)); + } + + /** + * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. + * + * @param consumer the consumer to consume + * @param value the value to consume by {@code consumer} + * @param <E> the type of checked exception the consumer may throw + */ + public static <E extends Throwable> void accept(final FailableDoubleConsumer<E> consumer, final double value) { + run(() -> consumer.accept(value)); + } + + /** + * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. + * + * @param consumer the consumer to consume + * @param value the value to consume by {@code consumer} + * @param <E> the type of checked exception the consumer may throw + */ + public static <E extends Throwable> void accept(final FailableIntConsumer<E> consumer, final int value) { + run(() -> consumer.accept(value)); + } + + /** + * Consumes a consumer and rethrows any exception as a {@link RuntimeException}. + * + * @param consumer the consumer to consume + * @param value the value to consume by {@code consumer} + * @param <E> the type of checked exception the consumer may throw + */ + public static <E extends Throwable> void accept(final FailableLongConsumer<E> consumer, final long value) { + run(() -> consumer.accept(value)); + } + + /** + * Applies a function and rethrows any exception as a {@link RuntimeException}. + * + * @param function the function to apply + * @param input1 the first input to apply {@code function} on + * @param input2 the second input to apply {@code function} on + * @param <T> the type of the first argument the function accepts + * @param <U> the type of the second argument the function accepts + * @param <R> the return type of the function + * @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) { + return get(() -> function.apply(input1, input2)); + } + + /** + * Applies a function and rethrows any exception as a {@link RuntimeException}. + * + * @param function the function to apply + * @param input the input to apply {@code function} on + * @param <T> the type of the argument the function accepts + * @param <R> the return type of the function + * @param <E> the type of checked exception the function may throw + * @return the value returned from the function + */ + public static <T, R, E extends Throwable> R apply(final FailableFunction<T, R, E> function, final T input) { + return get(() -> function.apply(input)); + } + + /** + * Applies a function and rethrows any exception as a {@link RuntimeException}. + * + * @param function the function to apply + * @param left the first input to apply {@code function} on + * @param right the second input to apply {@code function} on + * @param <E> the type of checked exception the function may throw + * @return the value returned from the function + */ + public static <E extends Throwable> double applyAsDouble(final FailableDoubleBinaryOperator<E> function, + final double left, final double right) { + return getAsDouble(() -> function.applyAsDouble(left, right)); + } + + /** + * Converts the given {@link FailableBiConsumer} into a standard {@link BiConsumer}. + * + * @param <T> the type of the first argument of the consumers + * @param <U> the type of the second argument of the consumers + * @param consumer a failable {@link BiConsumer} + * @return a standard {@link BiConsumer} + */ + public static <T, U> BiConsumer<T, U> asBiConsumer(final FailableBiConsumer<T, U, ?> consumer) { + return (input1, input2) -> accept(consumer, input1, input2); + } + + /** + * Converts the given {@link FailableBiFunction} into a standard {@link BiFunction}. + * + * @param <T> the type of the first argument of the input of the functions + * @param <U> the type of the second argument of the input of the functions + * @param <R> the type of the output of the functions + * @param function a {@link FailableBiFunction} + * @return a standard {@link BiFunction} + */ + public static <T, U, R> BiFunction<T, U, R> asBiFunction(final FailableBiFunction<T, U, R, ?> function) { + return (input1, input2) -> apply(function, input1, input2); + } + + /** + * Converts the given {@link FailableBiPredicate} into a standard {@link BiPredicate}. + * + * @param <T> the type of the first argument used by the predicates + * @param <U> the type of the second argument used by the predicates + * @param predicate a {@link FailableBiPredicate} + * @return a standard {@link BiPredicate} + */ + public static <T, U> BiPredicate<T, U> asBiPredicate(final FailableBiPredicate<T, U, ?> predicate) { + return (input1, input2) -> test(predicate, input1, input2); + } + + /** + * Converts the given {@link FailableCallable} into a standard {@link Callable}. + * + * @param <V> the type used by the callables + * @param callable a {@link FailableCallable} + * @return a standard {@link Callable} + */ + public static <V> Callable<V> asCallable(final FailableCallable<V, ?> callable) { + return () -> call(callable); + } + + /** + * Converts the given {@link FailableConsumer} into a standard {@link Consumer}. + * + * @param <T> the type used by the consumers + * @param consumer a {@link FailableConsumer} + * @return a standard {@link Consumer} + */ + public static <T> Consumer<T> asConsumer(final FailableConsumer<T, ?> consumer) { + return input -> accept(consumer, input); + } + + /** + * Converts the given {@link FailableFunction} into a standard {@link Function}. + * + * @param <T> the type of the input of the functions + * @param <R> the type of the output of the functions + * @param function a {code FailableFunction} + * @return a standard {@link Function} + */ + public static <T, R> Function<T, R> asFunction(final FailableFunction<T, R, ?> function) { + return input -> apply(function, input); + } + + /** + * Converts the given {@link FailablePredicate} into a standard {@link Predicate}. + * + * @param <T> the type used by the predicates + * @param predicate a {@link FailablePredicate} + * @return a standard {@link Predicate} + */ + public static <T> Predicate<T> asPredicate(final FailablePredicate<T, ?> predicate) { + return input -> test(predicate, input); + } + + /** + * Converts the given {@link FailableRunnable} into a standard {@link Runnable}. + * + * @param runnable a {@link FailableRunnable} + * @return a standard {@link Runnable} + */ + public static Runnable asRunnable(final FailableRunnable<?> runnable) { + return () -> run(runnable); + } + + /** + * Converts the given {@link FailableSupplier} into a standard {@link Supplier}. + * + * @param <T> the type supplied by the suppliers + * @param supplier a {@link FailableSupplier} + * @return a standard {@link Supplier} + */ + public static <T> Supplier<T> asSupplier(final FailableSupplier<T, ?> supplier) { + return () -> get(supplier); + } + + /** + * Calls a callable and rethrows any exception as a {@link RuntimeException}. + * + * @param callable the callable to call + * @param <V> the return type of the callable + * @param <E> the type of checked exception the callable may throw + * @return the value returned from the callable + */ + public static <V, E extends Throwable> V call(final FailableCallable<V, E> callable) { + return get(callable::call); + } + + /** + * Invokes a supplier, and returns the result. + * + * @param supplier The supplier to invoke. + * @param <T> The suppliers output type. + * @param <E> The type of checked exception, which the supplier can throw. + * @return The object, which has been created by the supplier + */ + public static <T, E extends Throwable> T get(final FailableSupplier<T, E> supplier) { + try { + return supplier.get(); + } catch (final Throwable t) { + throw rethrow(t); + } + } + + /** + * Invokes a boolean supplier, and returns the result. + * + * @param supplier The boolean supplier to invoke. + * @param <E> The type of checked exception, which the supplier can throw. + * @return The boolean, which has been created by the supplier + */ + public static <E extends Throwable> boolean getAsBoolean(final FailableBooleanSupplier<E> supplier) { + try { + return supplier.getAsBoolean(); + } catch (final Throwable t) { + throw rethrow(t); + } + } + + /** + * Invokes a double supplier, and returns the result. + * + * @param supplier The double supplier to invoke. + * @param <E> The type of checked exception, which the supplier can throw. + * @return The double, which has been created by the supplier + */ + public static <E extends Throwable> double getAsDouble(final FailableDoubleSupplier<E> supplier) { + try { + return supplier.getAsDouble(); + } catch (final Throwable t) { + throw rethrow(t); + } + } + + /** + * Invokes an int supplier, and returns the result. + * + * @param supplier The int supplier to invoke. + * @param <E> The type of checked exception, which the supplier can throw. + * @return The int, which has been created by the supplier + */ + public static <E extends Throwable> int getAsInt(final FailableIntSupplier<E> supplier) { + try { + return supplier.getAsInt(); + } catch (final Throwable t) { + throw rethrow(t); + } + } + + /** + * Invokes a long supplier, and returns the result. + * + * @param supplier The long supplier to invoke. + * @param <E> The type of checked exception, which the supplier can throw. + * @return The long, which has been created by the supplier + */ + public static <E extends Throwable> long getAsLong(final FailableLongSupplier<E> supplier) { + try { + return supplier.getAsLong(); + } catch (final Throwable t) { + throw rethrow(t); + } + } + + /** + * Invokes a short supplier, and returns the result. + * + * @param supplier The short supplier to invoke. + * @param <E> The type of checked exception, which the supplier can throw. + * @return The short, which has been created by the supplier + */ + public static <E extends Throwable> short getAsShort(final FailableShortSupplier<E> supplier) { + try { + return supplier.getAsShort(); + } catch (final Throwable t) { + throw rethrow(t); + } + } + + /** + * Rethrows a {@link Throwable} as an unchecked exception. If the argument is already unchecked, namely a + * {@link RuntimeException} or {@link Error} then the argument will be rethrown without modification. If the + * exception is {@link IOException} then it will be wrapped into a {@link UncheckedIOException}. In every other + * cases the exception will be wrapped into a {@code + * UndeclaredThrowableException} + * + * <p> + * Note that there is a declared return type for this method, even though it never returns. The reason for that is + * to support the usual pattern: + * </p> + * + * <pre> + * throw rethrow(myUncheckedException); + * </pre> + * + * <p> + * instead of just calling the method. This pattern may help the Java compiler to recognize that at that point an + * exception will be thrown and the code flow analysis will not demand otherwise mandatory commands that could + * follow the method call, like a {@code return} statement from a value returning method. + * </p> + * + * @param throwable The throwable to rethrow possibly wrapped into an unchecked exception + * @return Never returns anything, this method never terminates normally. + */ + public static RuntimeException rethrow(final Throwable throwable) { + Objects.requireNonNull(throwable, "throwable"); + if (throwable instanceof RuntimeException) { + throw (RuntimeException) throwable; + } + if (throwable instanceof Error) { + throw (Error) throwable; + } + if (throwable instanceof IOException) { + throw new UncheckedIOException((IOException) throwable); + } + throw new UndeclaredThrowableException(throwable); + } + + /** + * Runs a runnable and rethrows any exception as a {@link RuntimeException}. + * + * @param runnable The runnable to run + * @param <E> the type of checked exception the runnable may throw + */ + public static <E extends Throwable> void run(final FailableRunnable<E> runnable) { + try { + runnable.run(); + } catch (final Throwable t) { + throw rethrow(t); + } + } + + /** + * Converts the given collection into a {@link FailableStream}. The {@link FailableStream} consists of the + * collections elements. Shortcut for + * + * <pre> + * Functions.stream(collection.stream()); + * </pre> + * + * @param collection The collection, which is being converted into a {@link FailableStream}. + * @param <E> The collections element type. (In turn, the result streams element type.) + * @return The created {@link FailableStream}. + */ + public static <E> FailableStream<E> stream(final Collection<E> collection) { + return new FailableStream<>(collection.stream()); + } + + /** + * Converts the given stream into a {@link FailableStream}. The {@link FailableStream} consists of the same + * elements, than the input stream. However, failable lambdas, like {@link FailablePredicate}, + * {@link FailableFunction}, and {@link FailableConsumer} may be applied, rather than {@link Predicate}, + * {@link Function}, {@link Consumer}, etc. + * + * @param stream The stream, which is being converted into a {@link FailableStream}. + * @param <T> The streams element type. + * @return The created {@link FailableStream}. + */ + public static <T> FailableStream<T> stream(final Stream<T> stream) { + return new FailableStream<>(stream); + } + + /** + * Tests a predicate and rethrows any exception as a {@link RuntimeException}. + * + * @param predicate the predicate to test + * @param object1 the first input to test by {@code predicate} + * @param object2 the second input to test by {@code predicate} + * @param <T> the type of the first argument the predicate tests + * @param <U> the type of the second argument the predicate tests + * @param <E> the type of checked exception the predicate may throw + * @return the boolean value returned by the predicate + */ + public static <T, U, E extends Throwable> boolean test(final FailableBiPredicate<T, U, E> predicate, + final T object1, final U object2) { + return getAsBoolean(() -> predicate.test(object1, object2)); + } + + /** + * Tests a predicate and rethrows any exception as a {@link RuntimeException}. + * + * @param predicate the predicate to test + * @param object the input to test by {@code predicate} + * @param <T> the type of argument the predicate tests + * @param <E> the type of checked exception the predicate may throw + * @return the boolean value returned by the predicate + */ + public static <T, E extends Throwable> boolean test(final FailablePredicate<T, E> predicate, final T object) { + return getAsBoolean(() -> predicate.test(object)); + } + + /** + * A simple try-with-resources implementation, that can be used, if your objects do not implement the + * {@link AutoCloseable} interface. The method executes the {@code action}. The method guarantees, that <em>all</em> + * the {@code resources} are being executed, in the given order, afterwards, and regardless of success, or failure. + * If either the original action, or any of the resource action fails, then the <em>first</em> failure (AKA + * {@link Throwable}) is rethrown. Example use: + * + * <pre> + * final FileInputStream fis = new FileInputStream("my.file"); + * Functions.tryWithResources(useInputStream(fis), null, () -> fis.close()); + * </pre> + * + * @param action The action to execute. This object <em>will</em> always be invoked. + * @param errorHandler An optional error handler, which will be invoked finally, if any error occurred. The error + * handler will receive the first error, AKA {@link Throwable}. + * @param resources The resource actions to execute. <em>All</em> resource actions will be invoked, in the given + * order. A resource action is an instance of {@link FailableRunnable}, which will be executed. + * @see #tryWithResources(FailableRunnable, FailableRunnable...) + */ + @SafeVarargs + public static void tryWithResources(final FailableRunnable<? extends Throwable> action, + final FailableConsumer<Throwable, ? extends Throwable> errorHandler, + final FailableRunnable<? extends Throwable>... resources) { + final FailableConsumer<Throwable, ? extends Throwable> actualErrorHandler; + if (errorHandler == null) { + actualErrorHandler = Failable::rethrow; + } else { + actualErrorHandler = errorHandler; + } + Streams.of(resources).forEach(r -> Objects.requireNonNull(r, "runnable")); + Throwable th = null; + try { + action.run(); + } catch (final Throwable t) { + th = t; + } + if (resources != null) { + for (final FailableRunnable<?> runnable : resources) { + try { + runnable.run(); + } catch (final Throwable t) { + if (th == null) { + th = t; + } + } + } + } + if (th != null) { + try { + actualErrorHandler.accept(th); + } catch (final Throwable t) { + throw rethrow(t); + } + } + } + + /** + * A simple try-with-resources implementation, that can be used, if your objects do not implement the + * {@link AutoCloseable} interface. The method executes the {@code action}. The method guarantees, that <em>all</em> + * the {@code resources} are being executed, in the given order, afterwards, and regardless of success, or failure. + * If either the original action, or any of the resource action fails, then the <em>first</em> failure (AKA + * {@link Throwable}) is rethrown. Example use: + * + * <pre> + * final FileInputStream fis = new FileInputStream("my.file"); + * Functions.tryWithResources(useInputStream(fis), () -> fis.close()); + * </pre> + * + * @param action The action to execute. This object <em>will</em> always be invoked. + * @param resources The resource actions to execute. <em>All</em> resource actions will be invoked, in the given + * order. A resource action is an instance of {@link FailableRunnable}, which will be executed. + * @see #tryWithResources(FailableRunnable, FailableConsumer, FailableRunnable...) + */ + @SafeVarargs + public static void tryWithResources(final FailableRunnable<? extends Throwable> action, + final FailableRunnable<? extends Throwable>... resources) { + tryWithResources(action, null, resources); + } + + private Failable() { + // empty + } + +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableBiConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableBiConsumer.java new file mode 100644 index 000000000..823a6496d --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableBiConsumer.java @@ -0,0 +1,73 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.BiConsumer; + +/** + * A functional interface like {@link BiConsumer} that declares a {@link Throwable}. + * + * @param <T> Consumed type 1. + * @param <U> Consumed type 2. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableBiConsumer<T, U, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableBiConsumer NOP = (t, u) -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @param <T> Consumed type 1. + * @param <U> Consumed type 2. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, U, E extends Throwable> FailableBiConsumer<T, U, E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param t the first parameter for the consumable to accept + * @param u the second parameter for the consumable to accept + * @throws E Thrown when the consumer fails. + */ + void accept(T t, U u) throws E; + + /** + * Returns a composed {@link FailableBiConsumer} like {@link BiConsumer#andThen(BiConsumer)}. + * + * @param after the operation to perform after this one. + * @return a composed {@link FailableBiConsumer} like {@link BiConsumer#andThen(BiConsumer)}. + * @throws NullPointerException when {@code after} is null. + */ + default FailableBiConsumer<T, U, E> andThen(final FailableBiConsumer<? super T, ? super U, E> after) { + Objects.requireNonNull(after); + return (t, u) -> { + accept(t, u); + after.accept(t, u); + }; + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableBiFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableBiFunction.java new file mode 100644 index 000000000..cabcd1921 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableBiFunction.java @@ -0,0 +1,75 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.BiFunction; +import java.util.function.Function; + +/** + * A functional interface like {@link BiFunction} that declares a {@link Throwable}. + * + * @param <T> Input type 1. + * @param <U> Input type 2. + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableBiFunction<T, U, R, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableBiFunction NOP = (t, u) -> null; + + /** + * Returns The NOP singleton. + * + * @param <T> Consumed type 1. + * @param <U> Consumed type 2. + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, U, R, E extends Throwable> FailableBiFunction<T, U, R, E> nop() { + return NOP; + } + + /** + * Returns a composed {@link FailableBiFunction} that like {@link BiFunction#andThen(Function)}. + * + * @param <V> the output type of the {@code after} function, and of the composed function. + * @param after the operation to perform after this one. + * @return a composed {@link FailableBiFunction} that like {@link BiFunction#andThen(Function)}. + * @throws NullPointerException when {@code after} is null. + */ + default <V> FailableBiFunction<T, U, V, E> andThen(final FailableFunction<? super R, ? extends V, E> after) { + Objects.requireNonNull(after); + return (final T t, final U u) -> after.apply(apply(t, u)); + } + + /** + * Applies this function. + * + * @param input1 the first input for the function + * @param input2 the second input for the function + * @return the result of the function + * @throws E Thrown when the function fails. + */ + R apply(T input1, U input2) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableBiPredicate.java b/src/main/java/org/apache/commons/lang3/function/FailableBiPredicate.java new file mode 100644 index 000000000..9fff9180e --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableBiPredicate.java @@ -0,0 +1,108 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.BiPredicate; + +/** + * A functional interface like {@link BiPredicate} that declares a {@link Throwable}. + * + * @param <T> Predicate type 1. + * @param <U> Predicate type 2. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@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> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, U, E extends Throwable> FailableBiPredicate<T, U, E> falsePredicate() { + return FALSE; + } + + /** + * Returns The TRUE singleton. + * + * @param <T> Consumed type 1. + * @param <U> Consumed type 2. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, U, E extends Throwable> FailableBiPredicate<T, U, E> truePredicate() { + return TRUE; + } + + /** + * Returns a composed {@link FailableBiPredicate} like {@link BiPredicate#and(BiPredicate)}. + * + * @param other a predicate that will be logically-ANDed with this predicate. + * @return a composed {@link FailableBiPredicate} like {@link BiPredicate#and(BiPredicate)}. + * @throws NullPointerException if other is null + */ + default FailableBiPredicate<T, U, E> and(final FailableBiPredicate<? super T, ? super U, E> other) { + Objects.requireNonNull(other); + return (final T t, final U u) -> test(t, u) && other.test(t, u); + } + + /** + * Returns a predicate that negates this predicate. + * + * @return a predicate that negates this predicate. + */ + default FailableBiPredicate<T, U, E> negate() { + return (final T t, final U u) -> !test(t, u); + } + + /** + * Returns a composed {@link FailableBiPredicate} like {@link BiPredicate#and(BiPredicate)}. + * + * @param other a predicate that will be logically-ORed with this predicate. + * @return a composed {@link FailableBiPredicate} like {@link BiPredicate#and(BiPredicate)}. + * @throws NullPointerException if other is null + */ + default FailableBiPredicate<T, U, E> or(final FailableBiPredicate<? super T, ? super U, E> other) { + Objects.requireNonNull(other); + return (final T t, final U u) -> test(t, u) || other.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 Thrown when this predicate fails. + */ + boolean test(T object1, U object2) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableBooleanSupplier.java b/src/main/java/org/apache/commons/lang3/function/FailableBooleanSupplier.java new file mode 100644 index 000000000..1e5dce262 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableBooleanSupplier.java @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.BooleanSupplier; + +/** + * A functional interface like {@link BooleanSupplier} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableBooleanSupplier<E extends Throwable> { + + /** + * Supplies a boolean. + * + * @return a result + * @throws E if the supplier fails + */ + boolean getAsBoolean() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableCallable.java b/src/main/java/org/apache/commons/lang3/function/FailableCallable.java new file mode 100644 index 000000000..0ac99a0ed --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableCallable.java @@ -0,0 +1,37 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +/** + * A functional interface like {@link java.util.concurrent.Callable} that declares a {@link Throwable}. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableCallable<R, E extends Throwable> { + + /** + * Calls the callable. + * + * @return The value returned from the callable + * @throws E if the callable fails + */ + R call() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableConsumer.java new file mode 100644 index 000000000..9565a8f15 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableConsumer.java @@ -0,0 +1,75 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.Consumer; +import java.util.function.Function; + +/** + * A functional interface like {@link Consumer} that declares a {@link Throwable}. + * + * <p> + * This is a functional interface whose functional method is {@link #accept(Object)}. + * </p> + * + * @param <T> the type of the input to the operation + * @param <E> Thrown exception type. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableConsumer<T, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableConsumer NOP = Function.identity()::apply; + + /** + * Returns The NOP singleton. + * + * @param <T> Consumed type 1. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailableConsumer<T, E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param object the parameter for the consumable to accept + * @throws E Thrown when the consumer fails. + */ + void accept(T object) throws E; + + /** + * Returns a composed {@link Consumer} like {@link Consumer#andThen(Consumer)}. + * + * @param after the operation to perform after this operation + * @return a composed {@link Consumer} like {@link Consumer#andThen(Consumer)}. + * @throws NullPointerException when {@code after} is null + */ + default FailableConsumer<T, E> andThen(final FailableConsumer<? super T, E> after) { + Objects.requireNonNull(after); + return (final T t) -> { + accept(t); + after.accept(t); + }; + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleBinaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleBinaryOperator.java new file mode 100644 index 000000000..0f23e4324 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleBinaryOperator.java @@ -0,0 +1,40 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.DoubleBinaryOperator; + +/** + * A functional interface like {@link DoubleBinaryOperator} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableDoubleBinaryOperator<E extends Throwable> { + + /** + * Applies this operator to the given operands. + * + * @param left the first operand + * @param right the second operand + * @return the operator result + * @throws E if the operation fails + */ + double applyAsDouble(double left, double right) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleConsumer.java new file mode 100644 index 000000000..88229ff60 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleConsumer.java @@ -0,0 +1,68 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.DoubleConsumer; + +/** + * A functional interface like {@link DoubleConsumer} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableDoubleConsumer<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableDoubleConsumer NOP = t -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableDoubleConsumer<E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param value the parameter for the consumable to accept + * @throws E Thrown when the consumer fails. + */ + void accept(double value) throws E; + + /** + * Returns a composed {@link FailableDoubleConsumer} like {@link DoubleConsumer#andThen(DoubleConsumer)}. + * + * @param after the operation to perform after this one. + * @return a composed {@link FailableDoubleConsumer} like {@link DoubleConsumer#andThen(DoubleConsumer)}. + * @throws NullPointerException when {@code after} is null. + */ + default FailableDoubleConsumer<E> andThen(final FailableDoubleConsumer<E> after) { + Objects.requireNonNull(after); + return (final double t) -> { + accept(t); + after.accept(t); + }; + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleFunction.java new file mode 100644 index 000000000..cdca5accd --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleFunction.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.DoubleFunction; + +/** + * A functional interface like {@link DoubleFunction} that declares a {@link Throwable}. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableDoubleFunction<R, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableDoubleFunction NOP = t -> null; + + /** + * Returns The NOP singleton. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <R, E extends Throwable> FailableDoubleFunction<R, E> nop() { + return NOP; + } + + /** + * Applies this function. + * + * @param input the input for the function + * @return the result of the function + * @throws E Thrown when the function fails. + */ + R apply(double input) 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 new file mode 100644 index 000000000..e54f501a7 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoublePredicate.java @@ -0,0 +1,101 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.DoublePredicate; + +/** + * A functional interface like {@link DoublePredicate} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@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> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableDoublePredicate<E> falsePredicate() { + return FALSE; + } + + /** + * Returns The TRUE singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableDoublePredicate<E> truePredicate() { + return TRUE; + } + + /** + * Returns a composed {@link FailableDoublePredicate} like {@link DoublePredicate#and(DoublePredicate)}. + * + * @param other a predicate that will be logically-ANDed with this predicate. + * @return a composed {@link FailableDoublePredicate} like {@link DoublePredicate#and(DoublePredicate)}. + * @throws NullPointerException if other is null + */ + default FailableDoublePredicate<E> and(final FailableDoublePredicate<E> other) { + Objects.requireNonNull(other); + return t -> test(t) && other.test(t); + } + + /** + * Returns a predicate that negates this predicate. + * + * @return a predicate that negates this predicate. + */ + default FailableDoublePredicate<E> negate() { + return t -> !test(t); + } + + /** + * Returns a composed {@link FailableDoublePredicate} like {@link DoublePredicate#and(DoublePredicate)}. + * + * @param other a predicate that will be logically-ORed with this predicate. + * @return a composed {@link FailableDoublePredicate} like {@link DoublePredicate#and(DoublePredicate)}. + * @throws NullPointerException if other is null + */ + default FailableDoublePredicate<E> or(final FailableDoublePredicate<E> other) { + Objects.requireNonNull(other); + return t -> test(t) || other.test(t); + } + + /** + * Tests the predicate. + * + * @param value the parameter for the predicate to accept. + * @return {@code true} if the input argument matches the predicate, {@code false} otherwise. + * @throws E Thrown when the consumer fails. + */ + boolean test(double value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleSupplier.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleSupplier.java new file mode 100644 index 000000000..1f923d9bb --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleSupplier.java @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.DoubleSupplier; + +/** + * A functional interface like {@link DoubleSupplier} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableDoubleSupplier<E extends Throwable> { + + /** + * Supplies a double. + * + * @return a result + * @throws E if the supplier fails + */ + double getAsDouble() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleToIntFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleToIntFunction.java new file mode 100644 index 000000000..e8a247c62 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleToIntFunction.java @@ -0,0 +1,53 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.DoubleToIntFunction; + +/** + * A functional interface like {@link DoubleToIntFunction} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableDoubleToIntFunction<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableDoubleToIntFunction NOP = t -> 0; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableDoubleToIntFunction<E> nop() { + return NOP; + } + + /** + * Applies this function to the given argument. + * + * @param value the function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + int applyAsInt(double value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleToLongFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleToLongFunction.java new file mode 100644 index 000000000..eeb3f3972 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleToLongFunction.java @@ -0,0 +1,53 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.DoubleToLongFunction; + +/** + * A functional interface like {@link DoubleToLongFunction} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableDoubleToLongFunction<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableDoubleToLongFunction NOP = t -> 0; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableDoubleToLongFunction<E> nop() { + return NOP; + } + + /** + * Applies this function to the given argument. + * + * @param value the function argument + * @return the function result + * @throws E if the operation fails + */ + int applyAsLong(double value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableDoubleUnaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableDoubleUnaryOperator.java new file mode 100644 index 000000000..91f98c6c7 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableDoubleUnaryOperator.java @@ -0,0 +1,93 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.DoubleUnaryOperator; + +/** + * A functional interface like {@link DoubleUnaryOperator} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +public interface FailableDoubleUnaryOperator<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableDoubleUnaryOperator NOP = t -> 0d; + + /** + * Returns a unary operator that always returns its input argument. + * + * @param <E> The kind of thrown exception or error. + * @return a unary operator that always returns its input argument + */ + static <E extends Throwable> FailableDoubleUnaryOperator<E> identity() { + return t -> t; + } + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableDoubleUnaryOperator<E> nop() { + return NOP; + } + + /** + * Returns a composed {@link FailableDoubleUnaryOperator} like + * {@link DoubleUnaryOperator#andThen(DoubleUnaryOperator)}. + * + * @param after the operator to apply after this one. + * @return a composed {@link FailableDoubleUnaryOperator} like + * {@link DoubleUnaryOperator#andThen(DoubleUnaryOperator)}. + * @throws NullPointerException if after is null. + * @see #compose(FailableDoubleUnaryOperator) + */ + default FailableDoubleUnaryOperator<E> andThen(final FailableDoubleUnaryOperator<E> after) { + Objects.requireNonNull(after); + return (final double t) -> after.applyAsDouble(applyAsDouble(t)); + } + + /** + * Applies this operator to the given operand. + * + * @param operand the operand + * @return the operator result + * @throws E Thrown when a consumer fails. + */ + double applyAsDouble(double operand) throws E; + + /** + * Returns a composed {@link FailableDoubleUnaryOperator} like + * {@link DoubleUnaryOperator#compose(DoubleUnaryOperator)}. + * + * @param before the operator to apply before this one. + * @return a composed {@link FailableDoubleUnaryOperator} like + * {@link DoubleUnaryOperator#compose(DoubleUnaryOperator)}. + * @throws NullPointerException if before is null. + * @see #andThen(FailableDoubleUnaryOperator) + */ + default FailableDoubleUnaryOperator<E> compose(final FailableDoubleUnaryOperator<E> before) { + Objects.requireNonNull(before); + return (final double v) -> applyAsDouble(before.applyAsDouble(v)); + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableFunction.java new file mode 100644 index 000000000..ef088c960 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableFunction.java @@ -0,0 +1,96 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.Function; + +/** + * A functional interface like {@link Function} that declares a {@link Throwable}. + * + * @param <T> Input type 1. + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableFunction<T, R, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableFunction NOP = t -> null; + + /** + * Returns a function that always returns its input argument. + * + * @param <T> the type of the input and output objects to the function + * @param <E> The kind of thrown exception or error. + * @return a function that always returns its input argument + */ + static <T, E extends Throwable> FailableFunction<T, T, E> identity() { + return t -> t; + } + + /** + * Returns The NOP singleton. + * + * @param <T> Consumed type 1. + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, R, E extends Throwable> FailableFunction<T, R, E> nop() { + return NOP; + } + + /** + * Returns a composed {@link FailableFunction} like {@link Function#andThen(Function)}. + * + * @param <V> the output type of the {@code after} function, and of the composed function. + * @return a composed {@link FailableFunction} like {@link Function#andThen(Function)}. + * @param after the operation to perform after this one. + * @throws NullPointerException when {@code after} is null. + */ + default <V> FailableFunction<T, V, E> andThen(final FailableFunction<? super R, ? extends V, E> after) { + Objects.requireNonNull(after); + return (final T t) -> after.apply(apply(t)); + } + + /** + * Applies this function. + * + * @param input the input for the function + * @return the result of the function + * @throws E Thrown when the function fails. + */ + R apply(T input) throws E; + + /** + * Returns a composed {@link FailableFunction} like {@link Function#compose(Function)}. + * + * @param <V> the input type to the {@code before} function, and to the composed function. + * @param before the operator to apply before this one. + * @return a composed {@link FailableFunction} like {@link Function#compose(Function)}. + * @throws NullPointerException if before is null. + * @see #andThen(FailableFunction) + */ + default <V> FailableFunction<V, R, E> compose(final FailableFunction<? super V, ? extends T, E> before) { + Objects.requireNonNull(before); + return (final V v) -> apply(before.apply(v)); + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntBinaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableIntBinaryOperator.java new file mode 100644 index 000000000..8f0015a50 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntBinaryOperator.java @@ -0,0 +1,40 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.IntBinaryOperator; + +/** + * A functional interface like {@link IntBinaryOperator} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableIntBinaryOperator<E extends Throwable> { + + /** + * Applies this operator to the given operands. + * + * @param left the first operand + * @param right the second operand + * @return the operator result + * @throws E if the operation fails + */ + int applyAsInt(int left, int right) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableIntConsumer.java new file mode 100644 index 000000000..a9330e1f2 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntConsumer.java @@ -0,0 +1,69 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.IntConsumer; + +/** + * A functional interface like {@link IntConsumer} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableIntConsumer<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableIntConsumer NOP = t -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableIntConsumer<E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param value the parameter for the consumable to accept + * @throws E Thrown when the consumer fails. + */ + void accept(int value) throws E; + + /** + * Returns a composed {@link FailableIntConsumer} like {@link IntConsumer#andThen(IntConsumer)}. + * + * @param after the operation to perform after this one. + * @return a composed {@link FailableLongConsumer} like {@link IntConsumer#andThen(IntConsumer)}. + * @throws NullPointerException if {@code after} is null + */ + default FailableIntConsumer<E> andThen(final FailableIntConsumer<E> after) { + Objects.requireNonNull(after); + return (final int t) -> { + accept(t); + after.accept(t); + }; + } + +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableIntFunction.java new file mode 100644 index 000000000..7f173defe --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntFunction.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.IntFunction; + +/** + * A functional interface like {@link IntFunction} that declares a {@link Throwable}. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableIntFunction<R, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableIntFunction NOP = t -> null; + + /** + * Returns The NOP singleton. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <R, E extends Throwable> FailableIntFunction<R, E> nop() { + return NOP; + } + + /** + * Applies this function. + * + * @param input the input for the function + * @return the result of the function + * @throws E Thrown when the function fails. + */ + R apply(int input) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntPredicate.java b/src/main/java/org/apache/commons/lang3/function/FailableIntPredicate.java new file mode 100644 index 000000000..1438e60f8 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntPredicate.java @@ -0,0 +1,101 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.IntPredicate; + +/** + * A functional interface like {@link IntPredicate} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@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> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableIntPredicate<E> falsePredicate() { + return FALSE; + } + + /** + * Returns The TRUE singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableIntPredicate<E> truePredicate() { + return TRUE; + } + + /** + * Returns a composed {@link FailableIntPredicate} like {@link IntPredicate#and(IntPredicate)}. + * + * @param other a predicate that will be logically-ANDed with this predicate. + * @return a composed {@link FailableIntPredicate} like {@link IntPredicate#and(IntPredicate)}. + * @throws NullPointerException if other is null + */ + default FailableIntPredicate<E> and(final FailableIntPredicate<E> other) { + Objects.requireNonNull(other); + return t -> test(t) && other.test(t); + } + + /** + * Returns a predicate that negates this predicate. + * + * @return a predicate that negates this predicate. + */ + default FailableIntPredicate<E> negate() { + return t -> !test(t); + } + + /** + * Returns a composed {@link FailableIntPredicate} like {@link IntPredicate#and(IntPredicate)}. + * + * @param other a predicate that will be logically-ORed with this predicate. + * @return a composed {@link FailableIntPredicate} like {@link IntPredicate#and(IntPredicate)}. + * @throws NullPointerException if other is null + */ + default FailableIntPredicate<E> or(final FailableIntPredicate<E> other) { + Objects.requireNonNull(other); + return t -> test(t) || other.test(t); + } + + /** + * Tests the predicate. + * + * @param value the parameter for the predicate to accept. + * @return {@code true} if the input argument matches the predicate, {@code false} otherwise. + * @throws E Thrown when the consumer fails. + */ + boolean test(int value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntSupplier.java b/src/main/java/org/apache/commons/lang3/function/FailableIntSupplier.java new file mode 100644 index 000000000..aa8ce8a19 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntSupplier.java @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.IntSupplier; + +/** + * A functional interface like {@link IntSupplier} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableIntSupplier<E extends Throwable> { + + /** + * Supplies an int. + * + * @return a result + * @throws E if the supplier fails + */ + int getAsInt() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntToDoubleFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableIntToDoubleFunction.java new file mode 100644 index 000000000..6d96cd700 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntToDoubleFunction.java @@ -0,0 +1,53 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.IntToDoubleFunction; + +/** + * A functional interface like {@link IntToDoubleFunction} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableIntToDoubleFunction<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableIntToDoubleFunction NOP = t -> 0d; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableIntToDoubleFunction<E> nop() { + return NOP; + } + + /** + * Applies this function to the given argument. + * + * @param value the function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + double applyAsDouble(int value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntToLongFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableIntToLongFunction.java new file mode 100644 index 000000000..4693fb56a --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntToLongFunction.java @@ -0,0 +1,53 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.IntToLongFunction; + +/** + * A functional interface like {@link IntToLongFunction} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableIntToLongFunction<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableIntToLongFunction NOP = t -> 0L; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableIntToLongFunction<E> nop() { + return NOP; + } + + /** + * Applies this function to the given argument. + * + * @param value the function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + long applyAsLong(int value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableIntUnaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableIntUnaryOperator.java new file mode 100644 index 000000000..a0d3cedc4 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableIntUnaryOperator.java @@ -0,0 +1,89 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.IntUnaryOperator; + +/** + * A functional interface like {@link IntUnaryOperator} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +public interface FailableIntUnaryOperator<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableIntUnaryOperator NOP = t -> 0; + + /** + * Returns a unary operator that always returns its input argument. + * + * @param <E> The kind of thrown exception or error. + * @return a unary operator that always returns its input argument + */ + static <E extends Throwable> FailableIntUnaryOperator<E> identity() { + return t -> t; + } + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableIntUnaryOperator<E> nop() { + return NOP; + } + + /** + * Returns a composed {@link FailableDoubleUnaryOperator} like {@link IntUnaryOperator#andThen(IntUnaryOperator)}. + * + * @param after the operator to apply after this one. + * @return a composed {@link FailableIntUnaryOperator} like {@link IntUnaryOperator#andThen(IntUnaryOperator)}. + * @throws NullPointerException if after is null. + * @see #compose(FailableIntUnaryOperator) + */ + default FailableIntUnaryOperator<E> andThen(final FailableIntUnaryOperator<E> after) { + Objects.requireNonNull(after); + return (final int t) -> after.applyAsInt(applyAsInt(t)); + } + + /** + * Applies this operator to the given operand. + * + * @param operand the operand + * @return the operator result + * @throws E Thrown when a consumer fails. + */ + int applyAsInt(int operand) throws E; + + /** + * Returns a composed {@link FailableIntUnaryOperator} like {@link IntUnaryOperator#compose(IntUnaryOperator)}. + * + * @param before the operator to apply before this one. + * @return a composed {@link FailableIntUnaryOperator} like {@link IntUnaryOperator#compose(IntUnaryOperator)}. + * @throws NullPointerException if before is null. + * @see #andThen(FailableIntUnaryOperator) + */ + default FailableIntUnaryOperator<E> compose(final FailableIntUnaryOperator<E> before) { + Objects.requireNonNull(before); + return (final int v) -> applyAsInt(before.applyAsInt(v)); + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongBinaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableLongBinaryOperator.java new file mode 100644 index 000000000..76b121429 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongBinaryOperator.java @@ -0,0 +1,40 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.LongBinaryOperator; + +/** + * A functional interface like {@link LongBinaryOperator} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableLongBinaryOperator<E extends Throwable> { + + /** + * Applies this operator to the given operands. + * + * @param left the first operand + * @param right the second operand + * @return the operator result + * @throws E if the operation fails + */ + long applyAsLong(long left, long right) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableLongConsumer.java new file mode 100644 index 000000000..946b4acf1 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongConsumer.java @@ -0,0 +1,68 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.LongConsumer; + +/** + * A functional interface like {@link LongConsumer} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableLongConsumer<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableLongConsumer NOP = t -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableLongConsumer<E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param object the parameter for the consumable to accept + * @throws E Thrown when the consumer fails. + */ + void accept(long object) throws E; + + /** + * Returns a composed {@link FailableLongConsumer} like {@link LongConsumer#andThen(LongConsumer)}. + * + * @param after the operation to perform after this one. + * @return a composed {@link FailableLongConsumer} like {@link LongConsumer#andThen(LongConsumer)}. + * @throws NullPointerException if {@code after} is null + */ + default FailableLongConsumer<E> andThen(final FailableLongConsumer<E> after) { + Objects.requireNonNull(after); + return (final long t) -> { + accept(t); + after.accept(t); + }; + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableLongFunction.java new file mode 100644 index 000000000..7ba5a12d6 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongFunction.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.LongFunction; + +/** + * A functional interface like {@link LongFunction} that declares a {@link Throwable}. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableLongFunction<R, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableLongFunction NOP = t -> null; + + /** + * Returns The NOP singleton. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <R, E extends Throwable> FailableLongFunction<R, E> nop() { + return NOP; + } + + /** + * Applies this function. + * + * @param input the input for the function + * @return the result of the function + * @throws E Thrown when the function fails. + */ + R apply(long input) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongPredicate.java b/src/main/java/org/apache/commons/lang3/function/FailableLongPredicate.java new file mode 100644 index 000000000..426d42891 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongPredicate.java @@ -0,0 +1,101 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.LongPredicate; + +/** + * A functional interface like {@link LongPredicate} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@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> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableLongPredicate<E> falsePredicate() { + return FALSE; + } + + /** + * Returns The TRUE singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableLongPredicate<E> truePredicate() { + return TRUE; + } + + /** + * Returns a composed {@link FailableLongPredicate} like {@link LongPredicate#and(LongPredicate)}. + * + * @param other a predicate that will be logically-ANDed with this predicate. + * @return a composed {@link FailableLongPredicate} like {@link LongPredicate#and(LongPredicate)}. + * @throws NullPointerException if other is null + */ + default FailableLongPredicate<E> and(final FailableLongPredicate<E> other) { + Objects.requireNonNull(other); + return t -> test(t) && other.test(t); + } + + /** + * Returns a predicate that negates this predicate. + * + * @return a predicate that negates this predicate. + */ + default FailableLongPredicate<E> negate() { + return t -> !test(t); + } + + /** + * Returns a composed {@link FailableLongPredicate} like {@link LongPredicate#and(LongPredicate)}. + * + * @param other a predicate that will be logically-ORed with this predicate. + * @return a composed {@link FailableLongPredicate} like {@link LongPredicate#and(LongPredicate)}. + * @throws NullPointerException if other is null + */ + default FailableLongPredicate<E> or(final FailableLongPredicate<E> other) { + Objects.requireNonNull(other); + return t -> test(t) || other.test(t); + } + + /** + * Tests the predicate. + * + * @param value the parameter for the predicate to accept. + * @return {@code true} if the input argument matches the predicate, {@code false} otherwise. + * @throws E Thrown when the consumer fails. + */ + boolean test(long value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongSupplier.java b/src/main/java/org/apache/commons/lang3/function/FailableLongSupplier.java new file mode 100644 index 000000000..1b6ee197f --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongSupplier.java @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.LongSupplier; + +/** + * A functional interface like {@link LongSupplier} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableLongSupplier<E extends Throwable> { + + /** + * Supplies a long. + * + * @return a result + * @throws E if the supplier fails + */ + long getAsLong() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongToDoubleFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableLongToDoubleFunction.java new file mode 100644 index 000000000..e0105bb72 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongToDoubleFunction.java @@ -0,0 +1,53 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.LongToDoubleFunction; + +/** + * A functional interface like {@link LongToDoubleFunction} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableLongToDoubleFunction<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableLongToDoubleFunction NOP = t -> 0d; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableLongToDoubleFunction<E> nop() { + return NOP; + } + + /** + * Applies this function to the given argument. + * + * @param value the function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + double applyAsDouble(long value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongToIntFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableLongToIntFunction.java new file mode 100644 index 000000000..e9a7a9efc --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongToIntFunction.java @@ -0,0 +1,53 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.LongToIntFunction; + +/** + * A functional interface like {@link LongToIntFunction} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableLongToIntFunction<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableLongToIntFunction NOP = t -> 0; + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableLongToIntFunction<E> nop() { + return NOP; + } + + /** + * Applies this function to the given argument. + * + * @param value the function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + int applyAsInt(long value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableLongUnaryOperator.java b/src/main/java/org/apache/commons/lang3/function/FailableLongUnaryOperator.java new file mode 100644 index 000000000..b58f79ddf --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableLongUnaryOperator.java @@ -0,0 +1,89 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.LongUnaryOperator; + +/** + * A functional interface like {@link LongUnaryOperator} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +public interface FailableLongUnaryOperator<E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableLongUnaryOperator NOP = t -> 0L; + + /** + * Returns a unary operator that always returns its input argument. + * + * @param <E> The kind of thrown exception or error. + * @return a unary operator that always returns its input argument + */ + static <E extends Throwable> FailableLongUnaryOperator<E> identity() { + return t -> t; + } + + /** + * Returns The NOP singleton. + * + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <E extends Throwable> FailableLongUnaryOperator<E> nop() { + return NOP; + } + + /** + * Returns a composed {@link FailableDoubleUnaryOperator} like {@link LongUnaryOperator#andThen(LongUnaryOperator)}. + * + * @param after the operator to apply after this one. + * @return a composed {@link FailableLongUnaryOperator} like {@link LongUnaryOperator#andThen(LongUnaryOperator)}. + * @throws NullPointerException if after is null. + * @see #compose(FailableLongUnaryOperator) + */ + default FailableLongUnaryOperator<E> andThen(final FailableLongUnaryOperator<E> after) { + Objects.requireNonNull(after); + return (final long t) -> after.applyAsLong(applyAsLong(t)); + } + + /** + * Applies this operator to the given operand. + * + * @param operand the operand + * @return the operator result + * @throws E Thrown when a consumer fails. + */ + long applyAsLong(long operand) throws E; + + /** + * Returns a composed {@link FailableLongUnaryOperator} like {@link LongUnaryOperator#compose(LongUnaryOperator)}. + * + * @param before the operator to apply before this one. + * @return a composed {@link FailableLongUnaryOperator} like {@link LongUnaryOperator#compose(LongUnaryOperator)}. + * @throws NullPointerException if before is null. + * @see #andThen(FailableLongUnaryOperator) + */ + default FailableLongUnaryOperator<E> compose(final FailableLongUnaryOperator<E> before) { + Objects.requireNonNull(before); + return (final long v) -> applyAsLong(before.applyAsLong(v)); + } +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableObjDoubleConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableObjDoubleConsumer.java new file mode 100644 index 000000000..1c986b91f --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableObjDoubleConsumer.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ObjDoubleConsumer; + +/** + * A functional interface like {@link ObjDoubleConsumer} that declares a {@link Throwable}. + * + * @param <T> the type of the object argument to the operation. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableObjDoubleConsumer<T, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableObjDoubleConsumer NOP = (t, u) -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the object argument to the operation. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailableObjDoubleConsumer<T, E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param object the object parameter for the consumable to accept. + * @param value the double parameter for the consumable to accept. + * @throws E Thrown when the consumer fails. + */ + void accept(T object, double value) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableObjIntConsumer.java b/src/main/java/org/apache/commons/lang3/function/FailableObjIntConsumer.java new file mode 100644 index 000000000..aa8c02cc1 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableObjIntConsumer.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ObjIntConsumer; + +/** + * A functional interface like {@link ObjIntConsumer} that declares a {@link Throwable}. + * + * @param <T> the type of the object argument to the operation. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableObjIntConsumer<T, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableObjIntConsumer NOP = (t, u) -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the object argument to the operation. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailableObjIntConsumer<T, E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param object the object 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 new file mode 100644 index 000000000..b6e5a3552 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableObjLongConsumer.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ObjLongConsumer; + +/** + * A functional interface like {@link ObjLongConsumer} that declares a {@link Throwable}. + * + * @param <T> the type of the object argument to the operation. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableObjLongConsumer<T, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableObjLongConsumer NOP = (t, u) -> {/* NOP */}; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the object argument to the operation. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailableObjLongConsumer<T, E> nop() { + return NOP; + } + + /** + * Accepts the consumer. + * + * @param object the object 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 new file mode 100644 index 000000000..bf4a5e370 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailablePredicate.java @@ -0,0 +1,104 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.Predicate; + +/** + * A functional interface like {@link Predicate} that declares a {@link Throwable}. + * + * @param <T> Predicate type. + * @param <E> The kind of thrown exception or error. + * @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> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailablePredicate<T, E> falsePredicate() { + return FALSE; + } + + /** + * Returns The TRUE singleton. + * + * @param <T> Predicate type. + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailablePredicate<T, E> truePredicate() { + return TRUE; + } + + /** + * Returns a composed {@link FailablePredicate} like {@link Predicate#and(Predicate)}. + * + * @param other a predicate that will be logically-ANDed with this predicate. + * @return a composed {@link FailablePredicate} like {@link Predicate#and(Predicate)}. + * @throws NullPointerException if other is null + */ + default FailablePredicate<T, E> and(final FailablePredicate<? super T, E> other) { + Objects.requireNonNull(other); + return t -> test(t) && other.test(t); + } + + /** + * Returns a predicate that negates this predicate. + * + * @return a predicate that negates this predicate. + */ + default FailablePredicate<T, E> negate() { + return t -> !test(t); + } + + /** + * Returns a composed {@link FailablePredicate} like {@link Predicate#and(Predicate)}. + * + * @param other a predicate that will be logically-ORed with this predicate. + * @return a composed {@link FailablePredicate} like {@link Predicate#and(Predicate)}. + * @throws NullPointerException if other is null + */ + default FailablePredicate<T, E> or(final FailablePredicate<? super T, E> other) { + Objects.requireNonNull(other); + return t -> test(t) || other.test(t); + } + + /** + * Tests the predicate. + * + * @param object the object to test the predicate on + * @return the predicate's evaluation + * @throws E if the predicate fails + */ + boolean test(T object) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableRunnable.java b/src/main/java/org/apache/commons/lang3/function/FailableRunnable.java new file mode 100644 index 000000000..46103c9e8 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableRunnable.java @@ -0,0 +1,35 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +/** + * A functional interface like {@link Runnable} that declares a kind of {@link Throwable}. + * + * @param <E> The kind of {@link Throwable}. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableRunnable<E extends Throwable> { + + /** + * Runs the function. + * + * @throws E Thrown when the function fails. + */ + void run() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableShortSupplier.java b/src/main/java/org/apache/commons/lang3/function/FailableShortSupplier.java new file mode 100644 index 000000000..325e08705 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableShortSupplier.java @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.IntSupplier; + +/** + * A functional interface like {@link IntSupplier} but for {@code short} that declares a {@link Throwable}. + * + * @param <E> The kind of thrown exception or error. + * @since 3.12.0 + */ +@FunctionalInterface +public interface FailableShortSupplier<E extends Throwable> { + + /** + * Supplies an int. + * + * @return a result + * @throws E if the supplier fails + */ + short getAsShort() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableSupplier.java b/src/main/java/org/apache/commons/lang3/function/FailableSupplier.java new file mode 100644 index 000000000..6f80af546 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableSupplier.java @@ -0,0 +1,39 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.Supplier; + +/** + * A functional interface like {@link Supplier} that declares a {@link Throwable}. + * + * @param <R> Return type. + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableSupplier<R, E extends Throwable> { + + /** + * Supplies an object + * + * @return a result + * @throws E if the supplier fails + */ + R get() throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableToDoubleBiFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableToDoubleBiFunction.java new file mode 100644 index 000000000..aea48e716 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableToDoubleBiFunction.java @@ -0,0 +1,58 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ToDoubleBiFunction; + +/** + * A functional interface like {@link ToDoubleBiFunction} that declares a {@link Throwable}. + * + * @param <T> the type of the first argument to the function + * @param <U> the type of the second argument to the function + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableToDoubleBiFunction<T, U, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableToDoubleBiFunction NOP = (t, u) -> 0d; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the first argument to the function + * @param <U> the type of the second argument to the function + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, U, E extends Throwable> FailableToDoubleBiFunction<T, U, E> nop() { + return NOP; + } + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument + * @param u the second function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + double applyAsDouble(T t, U u) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableToDoubleFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableToDoubleFunction.java new file mode 100644 index 000000000..b65591ca2 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableToDoubleFunction.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ToDoubleFunction; + +/** + * A functional interface like {@link ToDoubleFunction} that declares a {@link Throwable}. + * + * @param <T> the type of the argument to the function + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableToDoubleFunction<T, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableToDoubleFunction NOP = t -> 0d; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the argument to the function + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailableToDoubleFunction<T, E> nop() { + return NOP; + } + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + double applyAsDouble(T t) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableToIntBiFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableToIntBiFunction.java new file mode 100644 index 000000000..67617134f --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableToIntBiFunction.java @@ -0,0 +1,58 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ToIntBiFunction; + +/** + * A functional interface like {@link ToIntBiFunction} that declares a {@link Throwable}. + * + * @param <T> the type of the first argument to the function + * @param <U> the type of the second argument to the function + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableToIntBiFunction<T, U, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableToIntBiFunction NOP = (t, u) -> 0; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the first argument to the function + * @param <U> the type of the second argument to the function + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, U, E extends Throwable> FailableToIntBiFunction<T, U, E> nop() { + return NOP; + } + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument + * @param u the second function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + int applyAsInt(T t, U u) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableToIntFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableToIntFunction.java new file mode 100644 index 000000000..711115754 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableToIntFunction.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ToIntFunction; + +/** + * A functional interface like {@link ToIntFunction} that declares a {@link Throwable}. + * + * @param <T> the type of the argument to the function + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableToIntFunction<T, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableToIntFunction NOP = t -> 0; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the argument to the function + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailableToIntFunction<T, E> nop() { + return NOP; + } + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + int applyAsInt(T t) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableToLongBiFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableToLongBiFunction.java new file mode 100644 index 000000000..3c0d5f7ed --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableToLongBiFunction.java @@ -0,0 +1,58 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ToLongBiFunction; + +/** + * A functional interface like {@link ToLongBiFunction} that declares a {@link Throwable}. + * + * @param <T> the type of the first argument to the function + * @param <U> the type of the second argument to the function + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableToLongBiFunction<T, U, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableToLongBiFunction NOP = (t, u) -> 0; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the first argument to the function + * @param <U> the type of the second argument to the function + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, U, E extends Throwable> FailableToLongBiFunction<T, U, E> nop() { + return NOP; + } + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument + * @param u the second function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + long applyAsLong(T t, U u) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/FailableToLongFunction.java b/src/main/java/org/apache/commons/lang3/function/FailableToLongFunction.java new file mode 100644 index 000000000..f093f7467 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/FailableToLongFunction.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.ToLongFunction; + +/** + * A functional interface like {@link ToLongFunction} that declares a {@link Throwable}. + * + * @param <T> the type of the first argument to the function + * @param <E> The kind of thrown exception or error. + * @since 3.11 + */ +@FunctionalInterface +public interface FailableToLongFunction<T, E extends Throwable> { + + /** NOP singleton */ + @SuppressWarnings("rawtypes") + FailableToLongFunction NOP = t -> 0L; + + /** + * Returns The NOP singleton. + * + * @param <T> the type of the argument to the function + * @param <E> The kind of thrown exception or error. + * @return The NOP singleton. + */ + static <T, E extends Throwable> FailableToLongFunction<T, E> nop() { + return NOP; + } + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument + * @return the function result + * @throws E Thrown when the function fails. + */ + long applyAsLong(T t) throws E; +} diff --git a/src/main/java/org/apache/commons/lang3/function/IntToCharFunction.java b/src/main/java/org/apache/commons/lang3/function/IntToCharFunction.java new file mode 100644 index 000000000..f3da38451 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/IntToCharFunction.java @@ -0,0 +1,44 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.Function; + +/** + * Represents a function that accepts an int-valued argument and produces a long-valued result. This is the + * {@code int}-to-{@code long} primitive specialization for {@link Function}. + * + * <p> + * This is a <a href="package-summary.html">functional interface</a> whose functional method is + * {@link #applyAsChar(int)}. + * </p> + * + * @see Function + * @since 3.13.0 + */ +@FunctionalInterface +public interface IntToCharFunction { + + /** + * Applies this function to the given argument. + * + * @param value the function argument. + * @return the function result. + */ + char applyAsChar(int value); +} diff --git a/src/main/java/org/apache/commons/lang3/function/MethodInvokers.java b/src/main/java/org/apache/commons/lang3/function/MethodInvokers.java new file mode 100644 index 000000000..b90f0c14f --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/MethodInvokers.java @@ -0,0 +1,259 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.lang.invoke.MethodHandle; +import java.lang.invoke.MethodHandleProxies; +import java.lang.invoke.MethodHandles; +import java.lang.reflect.Method; +import java.util.Objects; +import java.util.function.BiConsumer; +import java.util.function.BiFunction; +import java.util.function.Function; +import java.util.function.Supplier; + +import org.apache.commons.lang3.exception.UncheckedIllegalAccessException; + +/** + * Converts {@link Method} objects to lambdas. + * <p> + * More specifically, produces instances of single-method interfaces which redirect calls to methods; see + * {@link #asInterfaceInstance(Class, Method)}. + * </p> + * <h2>Calling supplier methods with no arguments</h2> + * <p> + * If the interface's single-method defines no arguments, use {@link #asFunction(Method)} and then apply the function + * passing in the object to receive the method call. + * </p> + * <p> + * For example to invoke {@link String#length()}: + * </p> + * + * <pre> + * final Method method = String.class.getMethod("length"); + * final Function<String, Integer> function = MethodInvokers.asFunction(method); + * assertEquals(3, function.apply("ABC")); + * </pre> + * + * <h2>Calling function methods with one argument</h2> + * <p> + * If the interface's single-method defines one argument, use {@link #asBiFunction(Method)} and then apply the function + * passing in the object to receive the method call. The second argument to the function is the only argument to the + * method. + * </p> + * <p> + * For example to invoke {@link String#charAt(int)}: + * </p> + * + * <pre> + * final Method method = String.class.getMethod("charAt", int.class); + * final BiFunction<String, Integer, Character> function = MethodInvokers.asBiFunction(method); + * assertEquals('C', function.apply("ABC", 2)); + * </pre> + * + * @since 3.13.0 + */ +public final class MethodInvokers { + + /** + * Produces a {@link BiConsumer} for a given <em>consumer</em> Method. For example, a classic setter method (as opposed + * to a fluent setter). You call the BiConsumer with two arguments: (1) the object receiving the method call, and (2) + * the method argument. + * + * @param <T> the type of the first argument to the operation: The type containing the Method. + * @param <U> the type of the second argument to the operation: The type of the method argument. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <T, U> BiConsumer<T, U> asBiConsumer(final Method method) { + return asInterfaceInstance(BiConsumer.class, method); + } + + /** + * Produces a {@link BiFunction} for a given a <em>function</em> Method. You call the BiFunction with two arguments: (1) + * the object receiving the method call, and (2) the method argument. The BiFunction return type must match the method's + * return type. + * <p> + * For example to invoke {@link String#charAt(int)}: + * </p> + * + * <pre> + * final Method method = String.class.getMethod("charAt", int.class); + * final BiFunction<String, Integer, Character> function = MethodInvokers.asBiFunction(method); + * assertEquals('C', function.apply("ABC", 2)); + * </pre> + * + * @param <T> the type of the first argument to the function: The type containing the method. + * @param <U> the type of the second argument to the function: the method argument type. + * @param <R> the type of the result of the function: The method return type. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <T, U, R> BiFunction<T, U, R> asBiFunction(final Method method) { + return asInterfaceInstance(BiFunction.class, method); + } + + /** + * Produces a {@link FailableBiConsumer} for a given <em>consumer</em> Method. For example, a classic setter method (as + * opposed to a fluent setter). You call the FailableBiConsumer with two arguments: (1) the object receiving the method + * call, and (2) the method argument. + * + * @param <T> the type of the first argument to the operation: The type containing the Method. + * @param <U> the type of the second argument to the operation: The type of the method argument. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <T, U> FailableBiConsumer<T, U, Throwable> asFailableBiConsumer(final Method method) { + return asInterfaceInstance(FailableBiConsumer.class, method); + } + + /** + * Produces a {@link FailableBiFunction} for a given a <em>function</em> Method. You call the FailableBiFunction with + * two arguments: (1) the object receiving the method call, and (2) the method argument. The BiFunction return type must + * match the method's return type. + * + * @param <T> the type of the first argument to the function: The type containing the method. + * @param <U> the type of the second argument to the function: the method argument type. + * @param <R> the type of the result of the function: The method return type. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <T, U, R> FailableBiFunction<T, U, R, Throwable> asFailableBiFunction(final Method method) { + return asInterfaceInstance(FailableBiFunction.class, method); + } + + /** + * Produces a {@link FailableFunction} for a given a <em>supplier</em> Method. You call the Function with one argument: + * the object receiving the method call. The FailableFunction return type must match the method's return type. + * + * @param <T> the type of the first argument to the function: The type containing the method. + * @param <R> the type of the result of the function: The method return type. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <T, R> FailableFunction<T, R, Throwable> asFailableFunction(final Method method) { + return asInterfaceInstance(FailableFunction.class, method); + } + + /** + * Produces a {@link FailableSupplier} for a given a <em>supplier</em> Method. The FailableSupplier return type must + * match the method's return type. + * <p> + * Only works with static methods. + * </p> + * + * @param <R> The Method return type. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <R> FailableSupplier<R, Throwable> asFailableSupplier(final Method method) { + return asInterfaceInstance(FailableSupplier.class, method); + } + + /** + * Produces a {@link Function} for a given a <em>supplier</em> Method. You call the Function with one argument: the + * object receiving the method call. The Function return type must match the method's return type. + * <p> + * For example to invoke {@link String#length()}: + * </p> + * + * <pre> + * final Method method = String.class.getMethod("length"); + * final Function<String, Integer> function = MethodInvokers.asFunction(method); + * assertEquals(3, function.apply("ABC")); + * </pre> + * + * @param <T> the type of the first argument to the function: The type containing the method. + * @param <R> the type of the result of the function: The method return type. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <T, R> Function<T, R> asFunction(final Method method) { + return asInterfaceInstance(Function.class, method); + } + + /** + * Produces an instance of the given single-method interface which redirects its calls to the given method. + * <p> + * For the definition of "single-method", see {@linkplain MethodHandleProxies#asInterfaceInstance(Class, MethodHandle)}. + * </p> + * + * @param <T> The interface type. + * @param interfaceClass a class object representing {@code T}. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + * @see MethodHandleProxies#asInterfaceInstance(Class, MethodHandle) + */ + public static <T> T asInterfaceInstance(final Class<T> interfaceClass, final Method method) { + return MethodHandleProxies.asInterfaceInstance(Objects.requireNonNull(interfaceClass, "interfaceClass"), unreflectUnchecked(method)); + } + + /** + * Produces a {@link Supplier} for a given a <em>supplier</em> Method. The Supplier return type must match the method's + * return type. + * <p> + * Only works with static methods. + * </p> + * + * @param <R> The Method return type. + * @param method the method to invoke. + * @return a correctly-typed wrapper for the given target. + */ + @SuppressWarnings("unchecked") + public static <R> Supplier<R> asSupplier(final Method method) { + return asInterfaceInstance(Supplier.class, method); + } + + /** + * Throws NullPointerException if {@code method} is {@code null}. + * + * @param method The method to test. + * @return The given method. + * @throws NullPointerException if {@code method} is {@code null}. + */ + private static Method requireMethod(final Method method) { + return Objects.requireNonNull(method, "method"); + } + + private static MethodHandle unreflect(final Method method) throws IllegalAccessException { + return MethodHandles.lookup().unreflect(requireMethod(method)); + } + + private static MethodHandle unreflectUnchecked(final Method method) { + try { + return unreflect(method); + } catch (final IllegalAccessException e) { + throw new UncheckedIllegalAccessException(e); + } + } + + /** + * No need to create instances. + */ + private MethodInvokers() { + // noop + } + +} diff --git a/src/main/java/org/apache/commons/lang3/function/Suppliers.java b/src/main/java/org/apache/commons/lang3/function/Suppliers.java new file mode 100644 index 000000000..6467a4780 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/Suppliers.java @@ -0,0 +1,40 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.Supplier; + +/** + * Helps use {@link Supplier}. + * + * @since 3.13.0 + */ +public class Suppliers { + + /** + * Null-safe call to {@link Supplier#get()}. + * + * @param <T> the type of results supplied by this supplier. + * @param supplier the supplier or null. + * @return Result of {@link Supplier#get()} or null. + */ + public static <T> T get(final Supplier<T> supplier) { + return supplier == null ? null : supplier.get(); + } + +} diff --git a/src/main/java/org/apache/commons/lang3/function/ToBooleanBiFunction.java b/src/main/java/org/apache/commons/lang3/function/ToBooleanBiFunction.java new file mode 100644 index 000000000..09bdb73eb --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/ToBooleanBiFunction.java @@ -0,0 +1,43 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.function.BiFunction; + +/** + * A function that accepts two arguments and produces a boolean result. This is the {@code boolean}-producing primitive + * specialization for {@link BiFunction}. + * + * @param <T> the type of the first argument to the function. + * @param <U> the type of the second argument to the function. + * + * @see BiFunction + * @since 3.12.0 + */ +@FunctionalInterface +public interface ToBooleanBiFunction<T, U> { + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument. + * @param u the second function argument. + * @return the function result. + */ + boolean applyAsBoolean(T t, U u); +} diff --git a/src/main/java/org/apache/commons/lang3/function/TriConsumer.java b/src/main/java/org/apache/commons/lang3/function/TriConsumer.java new file mode 100644 index 000000000..d0ba9b466 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/TriConsumer.java @@ -0,0 +1,71 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.Consumer; + +/** + * Represents an operation that accepts three input arguments and returns no result. This is the three-arity + * specialization of {@link Consumer}. Unlike most other functional interfaces, {@link TriConsumer} is expected to + * operate via side-effects. + * + * <p> + * This is a {@link FunctionalInterface} whose functional method is {@link #accept(Object, Object, Object)}. + * </p> + * <p> + * Provenance: Apache Log4j 2.7 + * </p> + * + * @param <T> type of the first argument + * @param <U> type of the second argument + * @param <V> type of the third argument + * @since 3.13.0 + */ +@FunctionalInterface +public interface TriConsumer<T, U, V> { + + /** + * Performs the operation given the specified arguments. + * + * @param k the first input argument + * @param v the second input argument + * @param s the third input argument + */ + void accept(T k, U v, V s); + + /** + * Returns a composed {@link TriConsumer} that performs, in sequence, this operation followed by the {@code after} + * operation. If performing either operation throws an exception, it is relayed to the caller of the composed + * operation. If performing this operation throws an exception, the {@code after} operation will not be performed. + * + * @param after the operation to perform after this operation. + * @return a composed {@link TriConsumer} that performs in sequence this operation followed by the {@code after} + * operation. + * @throws NullPointerException if {@code after} is null. + */ + default TriConsumer<T, U, V> andThen(final TriConsumer<? super T, ? super U, ? super V> after) { + Objects.requireNonNull(after); + + return (t, u, v) -> { + accept(t, u, v); + after.accept(t, u, v); + }; + } + +} diff --git a/src/main/java/org/apache/commons/lang3/function/TriFunction.java b/src/main/java/org/apache/commons/lang3/function/TriFunction.java new file mode 100644 index 000000000..7d8b81c50 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/TriFunction.java @@ -0,0 +1,66 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3.function; + +import java.util.Objects; +import java.util.function.Function; + +/** + * Represents a function that accepts three arguments and produces a result. This is the three-arity specialization of + * {@link Function}. + * + * <p> + * This is a <a href="package-summary.html">functional interface</a> whose functional method is + * {@link #apply(Object, Object, Object)}. + * </p> + * + * @param <T> the type of the first argument to the function + * @param <U> the type of the second argument to the function + * @param <V> the type of the third argument to the function + * @param <R> the type of the result of the function + * + * @see Function + * @since 3.12.0 + */ +@FunctionalInterface +public interface TriFunction<T, U, V, R> { + + /** + * Applies this function to the given arguments. + * + * @param t the first function argument + * @param u the second function argument + * @param v the third function argument + * @return the function result + */ + R apply(T t, U u, V v); + + /** + * Returns a composed function that first applies this function to its input, and then applies the {@code after} + * function to the result. If evaluation of either function throws an exception, it is relayed to the caller of the + * composed function. + * + * @param <W> the type of output of the {@code after} function, and of the composed function + * @param after the function to apply after this function is applied + * @return a composed function that first applies this function and then applies the {@code after} function + * @throws NullPointerException if after is null + */ + default <W> TriFunction<T, U, V, W> andThen(final Function<? super R, ? extends W> after) { + Objects.requireNonNull(after); + return (final T t, final U u, final V v) -> after.apply(apply(t, u, v)); + } +} 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 new file mode 100644 index 000000000..330e7c78d --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/function/package-info.java @@ -0,0 +1,29 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + * 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> + * + * @since 3.11 + */ +package org.apache.commons.lang3.function; |