de.caff.generics.function

## Interface FragilePredicate1<E extends java.lang.Exception,P>

- Type Parameters:
    `E` - exception type
    `P` - parameter type
  All Known Subinterfaces:
    FragilePredicate2<E,P1,P2>
  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 FragilePredicate1<E extends java.lang.Exception,P>

  A function with one argument which returns a boolean value, and throws a checked exception.

  Fragile 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(FragilePredicate1, FragilePredicate1)`,

  Author:
    Rammi
  See Also:
    `FragilePredicate2`

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <S> FragilePredicate1<E,S>` | `adapted(java.util.function.Function<? super S,? extends P> mapper)` Use this predicate on a different type.
    `default <T extends P> FragilePredicate1<E,T>` | `and_(java.util.function.Predicate<T> other)` Combine this and another predicate with logical and.
    `static <T,X extends java.lang.Exception> FragilePredicate1<X,T>` | `and(FragilePredicate1<? extends X,? super T> pred1, FragilePredicate1<? extends X,? super T> pred2)` Get a predicate which is the combination of two predicates with a logical and.
    `default FragilePredicate1<E,P>` | `and(java.util.function.Predicate<? super P> other)` Combine this and another predicate with logical and.
    `default FragilePredicate1<E,P>` | `negate()` Get the negation of this predicate.
    `default <T extends P> FragilePredicate1<E,T>` | `or_(java.util.function.Predicate<T> other)` Combine this and another predicate with logical or.
    `static <T,X extends java.lang.Exception> FragilePredicate1<X,T>` | `or(FragilePredicate1<? extends X,? super T> pred1, FragilePredicate1<? extends X,? super T> pred2)` Get a predicate which is the combination of two predicates with a logical or.
    `default FragilePredicate1<E,P>` | `or(java.util.function.Predicate<? super P> other)` Combine this and another predicate with logical or.
    `boolean` | `test(P arg)` Test the argument and check whether it evaluates.
    `default boolean` | `testNonNull(P argument, boolean fallback)` Test the argument only if it is not `null`, otherwise return the fallback.
    `default <T extends P> FragilePredicate1<E,T>` | `xor_(java.util.function.Predicate<T> other)` Combine this and another predicate with logical exclusive or.
    `static <T,X extends java.lang.Exception> FragilePredicate1<X,T>` | `xor(FragilePredicate1<? extends X,? super T> pred1, FragilePredicate1<? extends X,? super T> pred2)` Get a predicate which is the combination of two predicates with a logical exclusive or.
    `default FragilePredicate1<E,P>` | `xor(java.util.function.Predicate<? super P> other)` Combine this and another predicate with logical exclusive or.

- - ### Method Detail

    - #### test

          boolean test(P arg)
                throws E extends java.lang.Exception

      Test the argument and check whether it evaluates.
      Parameters:
        `arg` - argument to check
      Returns:
        `true` if the argument evaluates to `true`,
        `false` if not
      Throws:
        `E` - checked exception thrown by implementation
        `E extends java.lang.Exception`

    - #### testNonNull

          default boolean testNonNull(P argument,
                                      boolean fallback)
                               throws E extends java.lang.Exception

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

      Using this invocation it is guaranteed that `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
      Throws:
        `E` - checked exception thrown by implementation
        `E extends java.lang.Exception`

    - #### and

          @NotNull
          default FragilePredicate1<E,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.
      Parameters:
        `other` - other predicate to be chained with logical and
      Returns:
        predicates combined with logical and
      See Also:
        `and(FragilePredicate1, FragilePredicate1)`, `and_(Predicate)`

    - #### and_

          @NotNull
          default <T extends P> FragilePredicate1<E,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(FragilePredicate1, FragilePredicate1)`, `and(Predicate)`

    - #### or

          @NotNull
          default FragilePredicate1<E,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.
      Parameters:
        `other` - the other predicate to be chained with logical or
      Returns:
        predicates combined with logical or
      See Also:
        `or(FragilePredicate1, FragilePredicate1)`, `or_(Predicate)`

    - #### or_

          @NotNull
          default <T extends P> FragilePredicate1<E,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(FragilePredicate1, FragilePredicate1)`, `or(Predicate)`

    - #### xor

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

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

    - #### xor_

          @NotNull
          default <T extends P> FragilePredicate1<E,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 widening 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(FragilePredicate1, FragilePredicate1)`, `xor(Predicate)`

    - #### negate

          @NotNull
          default FragilePredicate1<E,P> negate()

      Get the negation of this predicate.
      Returns:
        negation of this predicate

    - #### adapted

          @NotNull
          default <S> FragilePredicate1<E,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

    - #### and

          @NotNull
          static <T,X extends java.lang.Exception> FragilePredicate1<X,T> and(@NotNull
                                                                                       FragilePredicate1<? extends X,? super T> pred1,
                                                                                       @NotNull
                                                                                       FragilePredicate1<? extends X,? 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
        `X` - common exception type
      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,X extends java.lang.Exception> FragilePredicate1<X,T> or(@NotNull
                                                                                      FragilePredicate1<? extends X,? super T> pred1,
                                                                                      @NotNull
                                                                                      FragilePredicate1<? extends X,? 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
        `X` - common exception type
      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,X extends java.lang.Exception> FragilePredicate1<X,T> xor(@NotNull
                                                                                       FragilePredicate1<? extends X,? super T> pred1,
                                                                                       @NotNull
                                                                                       FragilePredicate1<? extends X,? 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
        `X` - common exception type
      Parameters:
        `pred1` - first predicate
        `pred2` - second predicate
      Returns:
        combination of both predicates with logical exclusive or
      See Also:
        `xor(Predicate)`, `xor_(Predicate)`