de.caff.generics.function

## Interface Predicate1<P>

- Type Parameters:
    `P` - parameter type
  All Superinterfaces:
    java.util.function.Predicate<P>
  All Known Subinterfaces:
    BooleanPredicate2, BytePredicate2, CharPredicate2, DoublePredicate2, FloatPredicate1, FloatPredicate2, IntPredicate2, LongPredicate2, Predicate2<P1,P2>, Predicate3<P1,P2,P3>, Predicate4<P1,P2,P3,P4>, Predicate5<P1,P2,P3,P4,P5>, Predicate6<P1,P2,P3,P4,P5,P6>, Predicate7<P1,P2,P3,P4,P5,P6,P7>, Predicate8<P1,P2,P3,P4,P5,P6,P7,P8>, Predicate9<P1,P2,P3,P4,P5,P6,P7,P8,P9>, ShortPredicate2
  All Known Implementing Classes:
    AndChecker, EqualsChecker, GreaterEqualsChecker, GreaterThanChecker, LessEqualsChecker, LessThanChecker, NegateCheckerWrapper, NotEqualsChecker, OrChecker
  Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

      @FunctionalInterface
      public interface Predicate1<P>
      extends java.util.function.Predicate<P>

  A function with one argument which returns a boolean value.

  Predicates can be chained to simulate boolean logic by `and(Predicate)`, `or(Predicate)`, `xor(Predicate)`, and `negate()`. The chaining does not always work as expected from standard Java expressions. Therefore there are versions of the above methods with an underscore suffix which allow to widen the type: `and_(Predicate)`, `or_(Predicate)`, `xor_(Predicate)`.

  There are also static methods which take care of the type fiddling transparently: `and(Predicate, Predicate)`,

  Useful for start values in algorithms or as default values are the two values returned by `alwaysTrue()` (a predicate which always returns `true` regardless the argument applied to the `Predicate.test(Object)` method) and `alwaysFalse()` (same for `false`).

  This also acts as a standard `Predicate`.

  Author:
    Rammi
  See Also:
    `Predicate2`, `Predicate3`, `Predicate4`, `Predicate5`, `Predicate6`, `Predicate7`, `Predicate8`, `Predicate9`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Predicate1<java.lang.Object>` | `ALWAYS_FALSE` Deprecated. Use `alwaysFalse()` instead as the returned predicate is smarter.
    `static Predicate1<java.lang.Object>` | `ALWAYS_TRUE` Deprecated. Use `alwaysTrue()` instead as the returned predicate is smarter.

  - ### Method Summary

    All Methods Static Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <S> Predicate1<S>` | `adapted(java.util.function.Function<? super S,? extends P> mapper)` Use this predicate on a different type.
    `static <T> Predicate1<T>` | `alwaysFalse()` Get a predicate which always evaluates to `false`.
    `static <T> Predicate1<T>` | `alwaysTrue()` Get a predicate which always evaluates to `true`.
    `default <T extends P> Predicate1<T>` | `and_(java.util.function.Predicate<T> other)` Combine this and another predicate with logical and.
    `default Predicate1<P>` | `and(java.util.function.Predicate<? super P> other)` Combine this and another predicate with logical and.
    `static <T> Predicate1<T>` | `and(java.util.function.Predicate<? super T> pred1, java.util.function.Predicate<? super T> pred2)` Get a predicate which is the combination of two predicates with a logical and.
    `static <T> Predicate1<T>` | `from(java.util.function.Predicate<T> predicate)` Use a standard `Predicate` as a `Predicate1`, This is eg useful if your want to use the `xor(Predicate)` method.
    `static <T> Predicate1<T>` | `isEqual(T target)` Get a predicate which checks deep equality with the given target.
    `static <T> Predicate1<T>` | `isNull()` Get a predicate which checks whether a value is `null`.
    `default Predicate1<P>` | `negate()` Get the negation of this predicate.
    `static <T> Predicate1<T>` | `notNull()` Get a predicate which checks whether a value is not `null`.
    `default <T extends P> Predicate1<T>` | `or_(java.util.function.Predicate<T> other)` Combine this and another predicate with logical or.
    `default Predicate1<P>` | `or(java.util.function.Predicate<? super P> other)` Combine this and another predicate with logical or.
    `static <T> Predicate1<T>` | `or(java.util.function.Predicate<? super T> pred1, java.util.function.Predicate<? super T> pred2)` Get a predicate which is the combination of two predicates with a logical or.
    `default boolean` | `testNonNull(P argument, boolean fallback)` Test the argument only if it is not `null`, otherwise return the fallback.
    `default <T extends P> Predicate1<T>` | `xor_(java.util.function.Predicate<T> other)` Combine this and another predicate with logical exclusive or.
    `default Predicate1<P>` | `xor(java.util.function.Predicate<? super P> other)` Combine this and another predicate with logical exclusive or.
    `static <T> Predicate1<T>` | `xor(java.util.function.Predicate<? super T> pred1, java.util.function.Predicate<? super T> pred2)` Get a predicate which is the combination of two predicates with a logical exclusive or.

    - ### Methods inherited from interface java.util.function.Predicate

      `test`

- - ### Field Detail

    - #### ALWAYS_TRUE

          @Deprecated
          static final Predicate1<java.lang.Object> ALWAYS_TRUE

      Deprecated. Use `alwaysTrue()` instead as the returned predicate is smarter.
      Predicate which always returns true.

    - #### ALWAYS_FALSE

          @Deprecated
          static final Predicate1<java.lang.Object> ALWAYS_FALSE

      Deprecated. Use `alwaysFalse()` instead as the returned predicate is smarter.
      Predicate which always returns false.

  - ### Method Detail

    - #### testNonNull

          default boolean testNonNull(P argument,
                                      boolean fallback)

      Test the argument only if it is not `null`, otherwise return the fallback.

      Using this invocation it is guaranteed that `Predicate.test(Object)` will always be called with a non-null argument.

      Parameters:
        `argument` - argument of this function
        `fallback` - fallback returned if `argument` is `null`
      Returns:
        the result of applying this predicate to the non-null `argument`, or `fallback` if `argument` is null

    - #### and

          @NotNull
          default Predicate1<P> and(@NotNull
                                             java.util.function.Predicate<? super P> other)

      Combine this and another predicate with logical and. The result will use shortcut evaluation, so if this predicate already returns `false` the other one is not evaluated.
      Specified by:
        `and` in interface `java.util.function.Predicate<P>`
      Parameters:
        `other` - other predicate to be chained with logical and
      Returns:
        predicates combined with logical and
      See Also:
        `and(Predicate, Predicate)`, `and_(Predicate)`

    - #### and_

          @NotNull
          default <T extends P> Predicate1<T> and_(@NotNull
                                                            java.util.function.Predicate<T> other)

      Combine this and another predicate with logical and. The result will use shortcut evaluation, so if this predicate already returns `false` the other one is not evaluated.

      Compared to `and(Predicate)` this method allows to widen the type of this predicate to the one of the other predicate like in standard Jave logical expressions, eg

             Predicate1<Object> nonNull = o -> o != null;
             Predicate1<String> notEmpty = s -> !s.isEmpty();
             // Predicate1<???> bad = nonNull.and(notEmpty);     // not possible as String is not a super type of Object
             Predicate1<String> valid = nonMull.and_(notEmpty);  // not nice, but it works

      Type Parameters:
        `T` - type on which the other predicate operates, also the type of the returned predicate
      Parameters:
        `other` - other predicate
      Returns:
        predicates combined with logical and
      See Also:
        `and(Predicate, Predicate)`, `and(Predicate)`

    - #### or

          @NotNull
          default Predicate1<P> or(@NotNull
                                            java.util.function.Predicate<? super P> other)

      Combine this and another predicate with logical or. The result will use shortcut evaluation, so if this predicate already returns `true` the other one is not evaluated.
      Specified by:
        `or` in interface `java.util.function.Predicate<P>`
      Parameters:
        `other` - other predicate to be chained with logical or
      Returns:
        predicates combined with logical or
      See Also:
        `or(Predicate, Predicate)`, `or_(Predicate)`

    - #### or_

          @NotNull
          default <T extends P> Predicate1<T> or_(@NotNull
                                                           java.util.function.Predicate<T> other)

      Combine this and another predicate with logical or. The result will use shortcut evaluation, so if this predicate already returns `true` the other one is not evaluated.

      Compared to `or(Predicate)` this method allows to widen the type of this predicate to the one of the other predicate like in standard Jave logical expressions, eg

             Predicate1<Object> isNull = o -> o == null;
             Predicate1<String> isEmpty = s -> !s.isEmpty();
             // Predicate1<???> bad = pred1.or(pred2);     // not possible as String is not a super type of Object
             Predicate1<String> useless = pred1.or_(pred2);  // not nice, but it works

      Type Parameters:
        `T` - type on which the other predicate operates, also the type of the returned predicate
      Parameters:
        `other` - other predicate
      Returns:
        predicates combined with logical or
      See Also:
        `or(Predicate, Predicate)`, `or(Predicate)`

    - #### xor

          @NotNull
          default Predicate1<P> xor(@NotNull
                                             java.util.function.Predicate<? super P> other)

      Combine this and another predicate with logical exclusive or.
      Parameters:
        `other` - other predicate to be chained with logical exclusive or
      Returns:
        predicates combined with logical exclusive or
      See Also:
        `xor(Predicate, Predicate)`, `xor_(Predicate)`

    - #### xor_

          @NotNull
          default <T extends P> Predicate1<T> xor_(@NotNull
                                                            java.util.function.Predicate<T> other)

      Combine this and another predicate with logical exclusive or. The result will use shortcut evaluation, so if this predicate already returns `true` the other one is not evaluated.

      Compared to `or(Predicate)` this method allows to widen the type of this predicate to the one of the other predicate like in standard Jave logical expressions, eg

             Predicate1<Object> isNull = o -> o == null;
             Predicate1<String> isEmpty = s -> !s.isEmpty();
             // Predicate1<???> bad = isNull.xor(isEmpty);     // not possible as String is not a super type of Object
             Predicate1<String> useless = isNull.xor_(isEmpty);  // bad example, but it works

      Type Parameters:
        `T` - type on which the other predicate operates, also the type of the returned predicate
      Parameters:
        `other` - other predicate
      Returns:
        predicates combined with logical exclusive or
      See Also:
        `xor(Predicate, Predicate)`, `xor(Predicate)`

    - #### negate

          @NotNull
          default Predicate1<P> negate()

      Get the negation of this predicate.
      Specified by:
        `negate` in interface `java.util.function.Predicate<P>`
      Returns:
        negation of this predicate

    - #### adapted

          @NotNull
          default <S> Predicate1<S> adapted(@NotNull
                                                     java.util.function.Function<? super S,? extends P> mapper)

      Use this predicate on a different type.
      Type Parameters:
        `S` - different type on which the returned predicate operates
      Parameters:
        `mapper` - mapper function which converts the different type to one this predicate accepts.
      Returns:
        predicate on the new type, base on this one

    - #### from

          @NotNull
          static <T> Predicate1<T> from(@NotNull
                                                 java.util.function.Predicate<T> predicate)

      Use a standard `Predicate` as a `Predicate1`, This is eg useful if your want to use the `xor(Predicate)` method.
      Type Parameters:
        `T` - argument type
      Parameters:
        `predicate` - standard predicate
      Returns:
        `Predicate1` view of given predicate

    - #### alwaysTrue

          @NotNull
          static <T> Predicate1<T> alwaysTrue()

      Get a predicate which always evaluates to `true`.
      Type Parameters:
        `T` - value type of predicate
      Returns:
        predicate always returning `true`

    - #### alwaysFalse

          @NotNull
          static <T> Predicate1<T> alwaysFalse()

      Get a predicate which always evaluates to `false`.
      Type Parameters:
        `T` - value type of predicate
      Returns:
        predicate always returning `false`

    - #### isNull

          @NotNull
          static <T> Predicate1<T> isNull()

      Get a predicate which checks whether a value is `null`.
      Type Parameters:
        `T` - value type
      Returns:
        predicate returning `true` if a value is `null`

    - #### notNull

          @NotNull
          static <T> Predicate1<T> notNull()

      Get a predicate which checks whether a value is not `null`.
      Type Parameters:
        `T` - value type
      Returns:
        predicate returning `true` if a value is not `null`

    - #### isEqual

          @NotNull
          static <T> Predicate1<T> isEqual(@Nullable
                                                    T target)

      Get a predicate which checks deep equality with the given target.

      Different to `Predicate.isEqual(Object)` this internally uses `Objects.deepEquals(Object, Object)` to check for equality.

      Specified by:
        `isEqual` in interface `java.util.function.Predicate<P>`
      Type Parameters:
        `T` - target type
      Parameters:
        `target` - target object, possibly `null`
      Returns:
        predicate for deep equality with the given `target`

    - #### and

          @NotNull
          static <T> Predicate1<T> and(@NotNull
                                                java.util.function.Predicate<? super T> pred1,
                                                @NotNull
                                                java.util.function.Predicate<? super T> pred2)

      Get a predicate which is the combination of two predicates with a logical and.

      This method takes care of always creating a predicate of the correct type without having to fiddle with `and(Predicate)` or `and_(Predicate)` depending on the types.

      The result will use shortcut evaluation, so if this predicate already returns `false` the other one is not evaluated.

      Type Parameters:
        `T` - resulting type, which is the most extending type of both `pred1`'s type and `pred2`'s type, so if neither type is extending the other this method will not compile
      Parameters:
        `pred1` - first predicate
        `pred2` - second predicate
      Returns:
        combination of both predicates with logical and
      See Also:
        `and(Predicate)`, `and_(Predicate)`

    - #### or

          @NotNull
          static <T> Predicate1<T> or(@NotNull
                                               java.util.function.Predicate<? super T> pred1,
                                               @NotNull
                                               java.util.function.Predicate<? super T> pred2)

      Get a predicate which is the combination of two predicates with a logical or.

      This method takes care of always creating a predicate of the correct type without having to fiddle with `or(Predicate)` or `or_(Predicate)` depending on the types.

      The result will use shortcut evaluation, so if this predicate already returns `false` the other one is not evaluated.

      Type Parameters:
        `T` - resulting type, which is the most extending type of both `pred1`'s type and `pred2`'s type, so if neither type is extending the other this method will not compile
      Parameters:
        `pred1` - first predicate
        `pred2` - second predicate
      Returns:
        combination of both predicates with logical or
      See Also:
        `or(Predicate)`, `or_(Predicate)`

    - #### xor

          @NotNull
          static <T> Predicate1<T> xor(@NotNull
                                                java.util.function.Predicate<? super T> pred1,
                                                @NotNull
                                                java.util.function.Predicate<? super T> pred2)

      Get a predicate which is the combination of two predicates with a logical exclusive or.

      This method takes care of always creating a predicate of the correct type without having to fiddle with `or(Predicate)` or `or_(Predicate)` depending on the types.

      The result will use shortcut evaluation, so if this predicate already returns `true` the other one is not evaluated.

      Type Parameters:
        `T` - resulting type, which is the most extending type of both `pred1`'s type and `pred2`'s type, so if neither type is extending the other this method will not compile
      Parameters:
        `pred1` - first predicate
        `pred2` - second predicate
      Returns:
        combination of both predicates with logical exclusive or
      See Also:
        `xor(Predicate)`, `xor_(Predicate)`