ru.progrm_jarvis.javacommons.util.function.BooleanPredicate Maven / Gradle / Ivy

Go to download
package ru.progrm_jarvis.javacommons.util.function;

import lombok.NonNull;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;

import java.util.function.Predicate;

/**
 * Represents a predicate (boolean-valued function) of one argument.
 * This is the primitive type specialization of {@link Predicate} for {@code boolean}.
 *
 * @see Predicate non-primitive generic equivalent
 */
@FunctionalInterface
public interface BooleanPredicate extends Predicate<@NotNull Boolean> {

    /**
     * Evaluates this predicate on the given argument.
     *
     * @param value the input argument
     * @return {@code true} if the input argument matches the predicate or {@code false} otherwise
     */
    boolean testAsBoolean(boolean value);

    @Override
    @Contract("null -> fail")
    default boolean test(final @NotNull Boolean value) {
        return testAsBoolean(value.booleanValue());
    }

    /**
     * Returns a composed predicate that represents a short-circuiting logical AND of this predicate and another.
     * When evaluating the composed predicate, if this predicate is {@code false},
     * then the {@code other} predicate is not evaluated.
     * Any exceptions thrown during evaluation of either predicate are relayed
     * to the caller; if evaluation of this predicate throws an exception, the
     * {@code other} predicate will not be evaluated.
     *
     * @param other a predicate that will be logically-ANDed with this predicate
     * @return a composed predicate that represents the short-circuiting logical AND
     * of this predicate and the {@code other} predicate
     *
     * @throws NullPointerException if other is {@code null}
     */
    @Contract(value = "null -> fail; _ -> _", pure = true)
    default @NotNull BooleanPredicate and(final @NonNull BooleanPredicate other) {
        return value -> testAsBoolean(value) && other.testAsBoolean(value);
    }

    @Override
    @Contract(value = "null -> fail; _ -> _", pure = true)
    default @NotNull BooleanPredicate and(final @NonNull Predicate< @NotNull ? super Boolean> other) {
        return value -> testAsBoolean(value) && other.test(value);
    }

    /**
     * Returns a composed predicate that represents a short-circuiting logical OR of this predicate and another.
     * When evaluating the composed predicate, if this predicate is {@code true},
     * then the {@code other} predicate is not evaluated.
     * Any exceptions thrown during evaluation of either predicate are relayed
     * to the caller; if evaluation of this predicate throws an exception, the
     * {@code other} predicate will not be evaluated.
     *
     * @param other a predicate that will be logically-ORed with this predicate
     * @return a composed predicate that represents the short-circuiting logical OR
     * of this predicate and the {@code other} predicate
     *
     * @throws NullPointerException if other is {@code null}
     */
    @Contract(value = "null -> fail; _ -> _", pure = true)
    default @NotNull BooleanPredicate or(final @NonNull BooleanPredicate other) {
        return value -> testAsBoolean(value) || other.testAsBoolean(value);
    }

    @Override
    @Contract(value = "null -> fail; _ -> _", pure = true)
    default @NotNull BooleanPredicate or(final @NonNull Predicate< @NotNull ? super Boolean> other) {
        return value -> testAsBoolean(value) || other.test(value);
    }

    @Override
    @Contract(value = "-> _", pure = true)
    default @NotNull BooleanPredicate negate() {
        return value -> !testAsBoolean(value);
    }

    /**
     * Returns a predicate that tests if two arguments are equal.
     *
     * @param value value with which to compare the tested one
     * @return a predicate that tests if two arguments are equal
     */
    @Contract(value = "_ -> _", pure = true)
    static @NotNull BooleanPredicate isEqual(final boolean value) {
        return tested -> tested == value;
    }

    /**
     * Returns a predicate that tests if two arguments are not equal.
     *
     * @param value value with which to compare the tested one
     * @return a predicate that tests if two arguments are not equal
     */
    @Contract(value = "_ -> _", pure = true)
    static @NotNull BooleanPredicate isNotEqual(final boolean value) {
        return tested -> tested != value;
    }

    /**
     * Creates a predicate which is always {@code true}.
     *
     * @return predicate which is always {@code true}
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull DoublePredicate alwaysTrue() {
        return value -> true;
    }

    /**
     * Creates a predicate which is always {@code false}.
     *
     * @return predicate which is always {@code false}
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull DoublePredicate alwaysFalse() {
        return value -> false;
    }

    /**
     * Returns a composed operator that first applies this operator and and then inverts the result.
     *
     * @return a composed operator that first applies this operator and then inverts the result
     */
    @Contract(value = "-> _", pure = true)
    default @NotNull BooleanPredicate invert() {
        return operand -> !testAsBoolean(operand);
    }

    /**
     * Returns an unary operator that always returns its input argument.
     *
     * @return an unary operator that always returns its input argument
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull BooleanPredicate identity() {
        return operand -> operand;
    }

    /**
     * Returns an unary operator that always returns inverted input argument.
     *
     * @return an unary operator that always returns inverted input argument
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull BooleanPredicate inversion() {
        return operand -> !operand;
    }
}