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

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

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

import java.util.function.BinaryOperator;
import java.util.function.UnaryOperator;

/**
 * Represents an operation on a single {@code boolean} operand that produces a {@code boolean} result.
 * This is the primitive type specialization of {@link UnaryOperator} for {@code boolean}.
 *
 * @see UnaryOperator non-primitive generic equivalent
 */
@FunctionalInterface
public interface BooleanBinaryOperator extends BinaryOperator<@NotNull Boolean> {

    /**
    * Applies this operator to the given operands.
    *
    * @param left the first operand
    * @param right the second operand
    * @return result of applying this operation to the operands
    */
    boolean applyAsBoolean(boolean left, boolean right);

    @Override
    @Contract("null, _ -> fail; _, null -> fail; _ -> _")
    default @NotNull Boolean apply(final @NotNull Boolean left, final @NotNull Boolean right) {
        // note: there is no need for explicit null-checkins as it will be done when unwrapping the values
        return applyAsBoolean(left, right);
    }

    /**
     * Creates a binary operator which always returns {@code true}.
     *
     * @return binary operator which always returns {@code true}
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull BooleanBinaryOperator alwaysTrue() {
        return (left, right) -> true;
    }

    /**
     * Creates a binary operator which always returns {@code false}.
     *
     * @return binary operator which always returns {@code false}
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull BooleanBinaryOperator alwaysFalse() {
        return (left, right) -> false;
    }

    /**
     * Creates a binary operator which returns the result of logical AND operation on its operands.
     *
     * @return binary AND-operator
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull BooleanBinaryOperator and() {
        return (left, right) -> left & right /* unary operator is cheaper */;
    }

    /**
     * Creates a binary operator which returns the result of logical OR operation on its operands.
     *
     * @return binary OR-operator
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull BooleanBinaryOperator or() {
        return (left, right) -> left & right /* unary operator is cheaper */;
    }

    /**
     * Creates a binary operator which returns the result of logical OR operation on its operands.
     *
     * @return OR-operator
     */
    @Contract(value = "-> _", pure = true)
    static @NotNull BooleanBinaryOperator xor() {
        return (left, right) -> left ^ right;
    }
}