de.caff.generics.function

## Interface Function1<R,P>

- Type Parameters:
    `R` - return type
    `P` - parameter type
  All Superinterfaces:
    java.util.function.Function<P,R>
  All Known Subinterfaces:
    BooleanFunction2<T>, ByteFunction2<T>, CharFunction2<T>, Copier<T>, DoubleFunction2<T>, FloatFunction2<T>, Function2<R,P1,P2>, Function3<R,P1,P2,P3>, Function4<R,P1,P2,P3,P4>, Function5<R,P1,P2,P3,P4,P5>, Function6<R,P1,P2,P3,P4,P5,P6>, Function7<R,P1,P2,P3,P4,P5,P6,P7>, Function8<R,P1,P2,P3,P4,P5,P6,P7,P8>, Function9<R,P1,P2,P3,P4,P5,P6,P7,P8,P9>, IntFunction2<T>, LongFunction2<T>, ShortFunction2<T>, TwoWayTypeConverter<T,S>
  All Known Implementing Classes:
    CarelessTypeConverter, CopyConverter, DereferencingTypeConverter, MapKeyConverter, MapKeyValueConverter, MapValueConverter, OrderedPairFirstExtractor, OrderedPairSecondExtractor, ReferencingTypeConverter, StringSplitTypeConverter, TransitiveTypeConverter
  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 Function1<R,P>
      extends java.util.function.Function<P,R>

  Function with one parameter.

  This is basically the same as `Function`, but is more extensible. As it is extending `Function` it can be used anywhere as a replacement.

  Author:
    Rammi
  See Also:
    `Function0`, `Function2`, `Function3`, `Function4`, `Function5`, `Function6`, `Function7`, `Function8`, `Function9`

- - ### Method Summary

    All Methods Static Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <T> Function1<R,T>` | `after(java.util.function.Function<? super T,? extends P> before)` Get a chained function which first applies the given function and then this one.
    `default <T> Function1<T,P>` | `andThen(java.util.function.Function<? super R,? extends T> after)` Get a chained function which first applies this function and then the given function.
    `default R` | `applyNonNull(P argument, R fallback)` Apply this function if the argument is not `null`, otherwise return the fallback.
    `default R` | `applyOrDefault(P argument, R fallback)` Apply this function, but take care to create a fallback.
    `static <RR,PP> Function1<RR,PP>` | `fallback(Function1<? extends RR,? super PP> func1, Function1<? extends RR,? super PP> func2)` Get a function which is a combination of two functions which calls the first function and returns its result.
    `static <RR,PP> Function1<RR,PP>` | `fallback(java.util.function.Predicate<? super RR> validCheck, Function1<? extends RR,? super PP> func1, Function1<? extends RR,? super PP> func2)` Get a function which is a combination of two functions which calls the first function and returns its result.
    `static <TT,PP,EE extends java.lang.Exception> Function1<TT,PP>` | `from(FragileFunction1<TT,EE,PP> ff)` Create a normal function from a fragile function.
    `static <RR,PP> Function1<RR,PP>` | `from(java.util.function.Function<PP,RR> func)` Make a `Function` usable as a `Function1`.
    `static <E extends java.lang.Exception,RR,PP> Function1<RR,PP>` | `nonFragile(FragileFunction1<? extends RR,E,? super PP> fragileFunction)` Convert a 1-argument function which might throw a checked exception into one which does throw an unchecked exception.
    `static <E extends java.lang.Exception,RR,PP> Function1<RR,PP>` | `nonFragile(FragileFunction1<? extends RR,E,? super PP> fragileFunction, RR fallback)` Convert a 1-argument function which might throw a checked exception into one which will return a default value instead of throwing an exception.
    `static <E extends java.lang.Exception,RR,PP> Function1<RR,PP>` | `nonFragileX(FragileFunction1<? extends RR,E,? super PP> fragileFunction, java.util.function.BiFunction<? super E,? super PP,? extends RR> exceptionHandler)` Convert a 1-argument function which might throw a checked exception into one for which you can decide what happens with the exception.
    `default Function0<R>` | `partial(P argument)` Create a zero argument function from this one by applying a constant argument.
    `default Function1<R,P>` | `withFallback(Function1<? extends R,? super P> fallback)` Get a function which calls a fallback function if this function returns `null`.

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

      `apply, compose, identity`

- - ### Method Detail

    - #### applyOrDefault

          @NotNull
          default R applyOrDefault(P argument,
                                            @NotNull
                                            R fallback)

      Apply this function, but take care to create a fallback. This will return the fallback when `Function.apply(Object)` returns `null`.
      Parameters:
        `argument` - argument of this function
        `fallback` - fallback value returned if function returns `null`
      Returns:
        the non-null result of calling `Function.apply(Object)`, or `fallback` if the result was `null`
      See Also:
        `applyNonNull(Object, Object)`

    - #### applyNonNull

          default R applyNonNull(P argument,
                                 R fallback)

      Apply this function if the argument is not `null`, otherwise return the fallback. The difference to `applyOrDefault(Object, Object)` is that this function is not applied when `argument` is `null`.

      Using this invocation it is guaranteed that `Function.apply(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 function to the non-null `argument`, or `fallback` if `argument` is null

    - #### withFallback

          @NotNull
          default Function1<R,P> withFallback(@NotNull
                                                       Function1<? extends R,? super P> fallback)

      Get a function which calls a fallback function if this function returns `null`.
      Parameters:
        `fallback` - fallback function called if this function returns `null` for a given parameter
      Returns:
        combined function providing a fallback
      See Also:
        `fallback(Function1, Function1)`, `applyOrDefault(Object, Object)`

    - #### partial

          @NotNull
          default Function0<R> partial(P argument)

      Create a zero argument function from this one by applying a constant argument. Although useless for pure functions it can be useful in cases where the zero argument function is a factory (and therefore not pure).
      Parameters:
        `argument` - constant argument
      Returns:
        zero argument function

    - #### after

          @NotNull
          default <T> Function1<R,T> after(@NotNull
                                                    java.util.function.Function<? super T,? extends P> before)

      Get a chained function which first applies the given function and then this one.
      Type Parameters:
        `T` - parameter type of returned function
      Parameters:
        `before` - function to apply first
      Returns:
        function chain

    - #### andThen

          @NotNull
          default <T> Function1<T,P> andThen(@NotNull
                                                      java.util.function.Function<? super R,? extends T> after)

      Get a chained function which first applies this function and then the given function.
      Specified by:
        `andThen` in interface `java.util.function.Function<P,R>`
      Type Parameters:
        `T` - result type of returned function
      Parameters:
        `after` - function to apply after this one
      Returns:
        function chain

    - #### from

          @NotNull
          static <TT,PP,EE extends java.lang.Exception> Function1<TT,PP> from(@NotNull
                                                                                       FragileFunction1<TT,EE,PP> ff)

      Create a normal function from a fragile function. This will throw an `EvaluationException` (an unchecked runtime exception) with the original exception as the cause.
      Type Parameters:
        `TT` - result type
        `PP` - parameter type
        `EE` - exception type
      Parameters:
        `ff` - fragile function
      Returns:
        normal function

    - #### from

          @NotNull
          static <RR,PP> Function1<RR,PP> from(@NotNull
                                                        java.util.function.Function<PP,RR> func)

      Make a `Function` usable as a `Function1`.
      Type Parameters:
        `RR` - result type
        `PP` - parameter type
      Parameters:
        `func` - standard function
      Returns:
        `Function1` view of the given function

    - #### fallback

          @NotNull
          static <RR,PP> Function1<RR,PP> fallback(@NotNull
                                                            Function1<? extends RR,? super PP> func1,
                                                            @NotNull
                                                            Function1<? extends RR,? super PP> func2)

      Get a function which is a combination of two functions which calls the first function and returns its result. Only if the first function returns `null` it will call the second function and return its result.
      Type Parameters:
        `PP` - parameter type of returned function, which is the most extending type of both `func1`'s parameter type and `func2`'s parameter type, so if neither type is extending the other this method will not compile
        `RR` - result type of returned function, which is the most restricting type of of both `func1`'s result type and `func2`'s result type, so if neither type is extending the other this method will not compile
      Parameters:
        `func1` - first function
        `func2` - second function
      Returns:
        combination of both function where the second one is only called if the first returns `null`
      See Also:
        `fallback(Predicate, Function1, Function1)`

    - #### fallback

          @NotNull
          static <RR,PP> Function1<RR,PP> fallback(@NotNull
                                                            java.util.function.Predicate<? super RR> validCheck,
                                                            @NotNull
                                                            Function1<? extends RR,? super PP> func1,
                                                            @NotNull
                                                            Function1<? extends RR,? super PP> func2)

      Get a function which is a combination of two functions which calls the first function and returns its result. Only if the first function returns a value which is invalid it will call the second function and return its result.
      Type Parameters:
        `PP` - parameter type of returned function, which is the most extending type of both `func1`'s parameter type and `func2`'s parameter type, so if neither type is extending the other this method will not compile
        `RR` - result type of returned function, which is the most restricting type of of both `func1`'s result type and `func2`'s result type, so if neither type is extending the other this method will not compile
      Parameters:
        `validCheck` - check which determines the validity of the return of `func1`, if the check returns `false` `func2` will be used to calculate the result of the returned function
        `func1` - first function
        `func2` - second function
      Returns:
        combination of both functions where the second one is only called if the first returns a value which the `fallbackCheck` identifies as invalid

    - #### nonFragile

          @NotNull
          static <E extends java.lang.Exception,RR,PP> Function1<RR,PP> nonFragile(@NotNull
                                                                                            FragileFunction1<? extends RR,E,? super PP> fragileFunction)

      Convert a 1-argument function which might throw a checked exception into one which does throw an unchecked exception. The returned function will instead throw an unchecked `WrappedFragileException` for any checked exception thrown during `Function.apply(Object)`.
      Type Parameters:
        `E` - exception type
        `RR` - result type of incoming and outgoing function.
        `PP` - type of parameter of both functions
      Parameters:
        `fragileFunction` - function throwing a checked exception
      Returns:
        non-fragile function
      Throws:
        `WrappedFragileException` - wrapping the original exception from `fragileFunction`

    - #### nonFragile

          @NotNull
          static <E extends java.lang.Exception,RR,PP> Function1<RR,PP> nonFragile(@NotNull
                                                                                            FragileFunction1<? extends RR,E,? super PP> fragileFunction,
                                                                                            RR fallback)

      Convert a 1-argument function which might throw a checked exception into one which will return a default value instead of throwing an exception. Please note that the exception is lost in this case.
      Type Parameters:
        `E` - exception type
        `RR` - result type of incoming and outgoing function.
        `PP` - type of parameter of both functions
      Parameters:
        `fragileFunction` - function throwing a checked exception
        `fallback` - fallback returned when `fragileFunction` has thrown an exception
      Returns:
        non-fragile function

    - #### nonFragileX

          @NotNull
          static <E extends java.lang.Exception,RR,PP> Function1<RR,PP> nonFragileX(@NotNull
                                                                                             FragileFunction1<? extends RR,E,? super PP> fragileFunction,
                                                                                             @NotNull
                                                                                             java.util.function.BiFunction<? super E,? super PP,? extends RR> exceptionHandler)

      Convert a 1-argument function which might throw a checked exception into one for which you can decide what happens with the exception. The exception handler allows
      - throw an unchecked exception instead (compare `nonFragile(FragileFunction1)`)
      - provide a fallback value (compare `nonFragile(FragileFunction1, Object)`)
      - include logging in one of the above
      - and more...
      Type Parameters:
        `E` - exception type
        `RR` - result type of incoming and outgoing function.
        `PP` - type of parameter of both functions
      Parameters:
        `fragileFunction` - function throwing a checked exception
        `exceptionHandler` - exception handler. Its return value will be used as return value of the returned function.
      Returns:
        non-fragile function