net.yetamine.lang.functional.Acceptor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of net.yetamine.lang Show documentation
Small extensions for the core Java language libraries.
There is a newer version: 1.3.0
package net.yetamine.lang.functional;

import java.util.Objects;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;

/**
 * A generic operation interface which is a convenient extension of the common
 * {@link Consumer} interface.
 *
 * @param 
 *            the type of the input to the operation
 */
@FunctionalInterface
public interface Acceptor extends Consumer {

    /**
     * Performs this operation on the given argument.
     *
     * 
     * This method provides a direct bridge to {@link Function}, but this
     * interface intentionally does not inherit from it, because it has a
     * different role and function composition is not well-suited for it.
     *
     * @param t
     *            the input argument
     *
     * @return the input argument
     */
    default T apply(T t) {
        accept(t);
        return t;
    }

    /**
     * @see java.util.function.Consumer#andThen(Consumer)
     */
    default Acceptor andThen(Consumer after) {
        Objects.requireNonNull(after);

        return t -> {
            accept(t);
            after.accept(t);
        };
    }

    /**
     * Returns a consumer that executes this consumer only if the given
     * predicate is satisfied for the actual argument.
     *
     * @param predicate
     *            the predicate to test the argument. It must not be
     *            {@code null}.
     *
     * @return a consumer guarded by the predicate
     */
    default Acceptor onlyIf(Predicate predicate) {
        Objects.requireNonNull(predicate);

        return t -> {
            if (predicate.test(t)) {
                accept(t);
            }
        };
    }

    /**
     * Returns a function that performs, in sequence, this operation followed
     * applying the specified mapping function on the argument.
     *
     * 

     * To turn this instance in an usual {@link Function} instance without any
     * change of the result, use {@link Function#identity()} as the argument.
     *
     * @param 
     *            the type of the mapping result
     * @param mapping
     *            the mapping function to apply. It must not be {@code null}.
     *
     * @return the composed function
     */
    default  Function finish(Function mapping) {
        Objects.requireNonNull(mapping);
        return t -> mapping.apply(apply(t));
    }

    /**
     * Provides a nothing-doing consumer.
     *
     * @param 
     *            the type of the accepted parameter
     *
     * @return a nothing-doing consumer
     */
    public static  Acceptor ignoring() {
        return o -> {
            // Do nothing
        };
    }

    /**
     * Returns a consumer that applies, in sequence, all given consumers.
     *
     * 
     * This method does not make any copy of the input, therefore the caller may
     * provide a dynamic underlying sequence, but on the other hand, the caller
     * is responsible for thread safety of the sequence, so that another thread
     * may iterate through the sequence, having a consistent snapshot.
     *
     * @param 
     *            the type of the input to the operation
     * @param sequence
     *            the sequence of the consumers to apply. It must not be
     *            {@code null} and it must not provide {@code null} elements.
     *
     * @return a consumer that applies, in sequence, all given consumers
     */
    static  Acceptor sequential(Iterable> sequence) {
        return Consumers.sequential(sequence)::accept;
    }
}