com.jnape.palatable.lambda.functions

## Interface Fn1<A,B>

- Type Parameters:
    `A` - The argument type
    `B` - The result type
  All Superinterfaces:
    Applicative<B,Fn1<A,?>>, Cartesian<A,B,Fn1<?,?>>, Cocartesian<A,B,Fn1<?,?>>, Contravariant<A,Profunctor<?,B,Fn1<?,?>>>, Functor<B,Fn1<A,?>>, Monad<B,Fn1<A,?>>, MonadReader<A,B,Fn1<A,?>>, MonadRec<B,Fn1<A,?>>, MonadWriter<A,B,Fn1<A,?>>, Profunctor<A,B,Fn1<?,?>>
  All Known Subinterfaces:
    BiMonoidFactory<A,B,C>, BiPredicate<A,B>, BiSemigroupFactory<A,B,C>, Effect<A>, Fn0<A>, Fn2<A,B,C>, Fn3<A,B,C,D>, Fn4<A,B,C,D,E>, Fn5<A,B,C,D,E,F>, Fn6<A,B,C,D,E,F,G>, Fn7<A,B,C,D,E,F,G,H>, Fn8<A,B,C,D,E,F,G,H,I>, Kleisli<A,B,M,MB>, Monoid<A>, MonoidFactory<A,B>, Predicate<A>, Semigroup<A>, SemigroupFactory<A,B>
  All Known Implementing Classes:
    Absent, AddAll, All, Alter, And, Any, AutoBracket, Between, Both, Bracket, CartesianProduct, CatMaybes, Clamp, CmpEq, CmpEqBy, Coalesce, Collapse, Collapse, Compose, Compose, Concat, Cons, Constantly, Cycle, Difference, Distinct, Downcast, Drop, DropWhile, Empty, Endo, EndoK, Eq, Filter, Find, First, Flatten, FoldLeft, FoldRight, Force, GroupBy, GT, GTBy, GTE, GTEBy, Head, Id, IfThenElse, InGroupsOf, Init, Inits, Intersection, Intersperse, Into, Into1, Into3, Into4, Into5, Into6, Into7, Into8, Iterate, Join, Last, Last, LazyRec, LeftAll, LeftAll, LeftAny, LeftAny, LiftA2, LiftA3, LiftA4, LiftA5, LiftA6, LiftA7, LT, LTBy, LTE, LTEBy, Magnetize, MagnetizeBy, Map, Matching, Max, MaxBy, Merge, Merge, MergeMaps, Min, MinBy, Not, Occurrences, Or, Over, Partition, Peek, Peek2, Pre, PrependAll, Present, PutAll, RateLimit, Re, ReduceLeft, ReduceRight, Repeat, Replicate, Reverse, RightAll, RightAll, RightAny, RightAny, RunAll, RunAll, ScanLeft, Sequence, Set, Size, Slide, Snoc, Sort, SortBy, SortWith, Span, Tail, Tails, Take, TakeWhile, Times, ToArray, ToCollection, ToMap, Trampoline, Trivial, Tupler2, Uncons, Under, Unfoldr, Union, Until, Upcast, View, Xor, Zip, ZipWith
  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 Fn1<A,B>
      extends MonadRec<B,Fn1<A,?>>, MonadReader<A,B,Fn1<A,?>>, MonadWriter<A,B,Fn1<A,?>>, Cartesian<A,B,Fn1<?,?>>, Cocartesian<A,B,Fn1<?,?>>

  A function taking a single argument. This is the core function type that all other function types extend and auto-curry with.

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <C,D> Fn2<A,C,D>` | `andThen(Fn2<? super B,? super C,? extends D> after)` Left-to-right composition between different arity functions.
    `default B` | `apply(A a)` Invoke this function explosively with the given argument.
    `default Fn1<A,Tuple2<A,B>>` | `carry()` Pair the covariantly-positioned carrier type with the contravariantly-positioned carrier type.
    `default <C> Fn1<Tuple2<C,A>,Tuple2<C,B>>` | `cartesian()` Pair a value with the input to this function, and preserve the paired value through to the output.
    `default Fn1<A,B>` | `censor(Fn1<? super A,? extends A> fn)` Update the accumulated state.
    `B` | `checkedApply(A a)` Invoke this function with the given argument, potentially throwing any `Throwable`.
    `default Fn1<A,Choice2<A,B>>` | `choose()` Choose between a successful result `b` or returning back the input, `a`.
    `default <C> Fn1<Choice2<C,A>,Choice2<C,B>>` | `cocartesian()` Choose between either applying this function or returning back a different result altogether.
    `default <Y,Z> Fn2<Y,Z,B>` | `compose(Fn2<? super Y,? super Z,? extends A> before)` Right-to-left composition between different arity functions.
    `default <Z> Fn1<Z,B>` | `contraMap(Fn1<? super Z,? extends A> fn)` Contravariantly map `A <- B`.
    `default <Z,C> Fn1<Z,C>` | `diMap(Fn1<? super Z,? extends A> lFn, Fn1<? super B,? extends C> rFn)` Exercise both `diMapL` and `diMapR` over this function in the same invocation.
    `default <Z> Fn1<Z,B>` | `diMapL(Fn1<? super Z,? extends A> fn)` Contravariantly map over the argument to this function, producing a function that takes the new argument type, and produces the same result.
    `default <C> Fn1<A,C>` | `diMapR(Fn1<? super B,? extends C> fn)` Covariantly map over the return value of this function, producing a function that takes the same argument, and produces the new result type.
    `default <C> Fn1<A,C>` | `discardL(Applicative<C,Fn1<A,?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `default <C> Fn1<A,B>` | `discardR(Applicative<C,Fn1<A,?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `default <C> Fn1<A,C>` | `flatMap(Fn1<? super B,? extends Monad<C,Fn1<A,?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `default <C> Fn1<A,C>` | `fmap(Fn1<? super B,? extends C> f)` Also left-to-right composition (sadly).
    `static <A,B> Fn1<A,B>` | `fn1(Fn1<? super A,? extends B> fn)` Static factory method for avoid explicit casting when using method references as `Fn1`s.
    `static <A,B> Fn1<A,B>` | `fromFunction(Function<? super A,? extends B> function)` Static factory method for wrapping a java `Function` in an `Fn1`.
    `default <C> Lazy<Fn1<A,C>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super B,? extends C>,Fn1<A,?>>> lazyAppFn)` Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
    `default <C> Fn1<A,Tuple2<B,C>>` | `listens(Fn1<? super A,? extends C> fn)` Map the accumulation into a value and pair it with the current output.
    `default Fn1<A,B>` | `local(Fn1<? super A,? extends A> fn)` Modify this `MonadReader's` environment after reading it but before running the effect.
    `default <C> Fn1<A,C>` | `pure(C c)` Lift the value `b` into this applicative functor.
    `static <A> Pure<Fn1<A,?>>` | `pureFn1()` The canonical `Pure` instance for `Fn1`.
    `default Fn0<B>` | `thunk(A a)` Convert this `Fn1` to an `Fn0` by supplying an argument to this function.
    `default Function<A,B>` | `toFunction()` Convert this `Fn1` to a java `Function`.
    `default <C> Fn1<A,C>` | `trampolineM(Fn1<? super B,? extends MonadRec<RecursiveResult<B,C>,Fn1<A,?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `default <Z> Fn2<Z,A,B>` | `widen()` Widen this function's argument list by prepending an ignored argument of any type to the front.
    `default <C> Fn1<A,C>` | `zip(Applicative<Fn1<? super B,? extends C>,Fn1<A,?>> appFn)` Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
    `default <C> Fn1<A,C>` | `zip(Fn2<A,B,C> appFn)`

    - ### Methods inherited from interface com.jnape.palatable.lambda.monad.Monad

      `join`

    - ### Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

      `coerce`

- - ### Method Detail

    - #### apply

          default B apply(A a)

      Invoke this function explosively with the given argument.
      Parameters:
        `a` - the argument
      Returns:
        the result of the function application

    - #### checkedApply

          B checkedApply(A a)
                  throws Throwable

      Invoke this function with the given argument, potentially throwing any `Throwable`.
      Parameters:
        `a` - the argument
      Returns:
        the result of the function application
      Throws:
        `Throwable` - anything possibly thrown by the function

    - #### thunk

          default Fn0<B> thunk(A a)

      Convert this `Fn1` to an `Fn0` by supplying an argument to this function. Useful for fixing an argument now, but deferring application until a later time.
      Parameters:
        `a` - the argument
      Returns:
        an `Fn0`

    - #### widen

          default <Z> Fn2<Z,A,B> widen()

      Widen this function's argument list by prepending an ignored argument of any type to the front.
      Type Parameters:
        `Z` - the new first argument type
      Returns:
        the widened function

    - #### toFunction

          default Function<A,B> toFunction()

      Convert this `Fn1` to a java `Function`.
      Returns:
        the `Function`

    - #### local

          default Fn1<A,B> local(Fn1<? super A,? extends A> fn)

      Modify this `MonadReader's` environment after reading it but before running the effect.
      Specified by:
        `local` in interface `MonadReader<A,B,Fn1<A,?>>`
      Parameters:
        `fn` - the modification function
      Returns:
        the `MonadReader` with a modified environment

    - #### listens

          default <C> Fn1<A,Tuple2<B,C>> listens(Fn1<? super A,? extends C> fn)

      Map the accumulation into a value and pair it with the current output.
      Specified by:
        `listens` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the mapped output
      Parameters:
        `fn` - the mapping function
      Returns:
        the updated `MonadWriter`

    - #### censor

          default Fn1<A,B> censor(Fn1<? super A,? extends A> fn)

      Update the accumulated state.
      Specified by:
        `censor` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Parameters:
        `fn` - the update function
      Returns:
        the updated `MonadWriter`

    - #### flatMap

          default <C> Fn1<A,C> flatMap(Fn1<? super B,? extends Monad<C,Fn1<A,?>>> f)

      Chain dependent computations that may continue or short-circuit based on previous results.
      Specified by:
        `flatMap` in interface `Monad<B,Fn1<A,?>>`
      Specified by:
        `flatMap` in interface `MonadReader<A,B,Fn1<A,?>>`
      Specified by:
        `flatMap` in interface `MonadRec<B,Fn1<A,?>>`
      Specified by:
        `flatMap` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the resulting monad parameter type
      Parameters:
        `f` - the dependent computation over A
      Returns:
        the new monad instance

    - #### fmap

          default <C> Fn1<A,C> fmap(Fn1<? super B,? extends C> f)

      Also left-to-right composition (sadly).
      Specified by:
        `fmap` in interface `Applicative<B,Fn1<A,?>>`
      Specified by:
        `fmap` in interface `Functor<B,Fn1<A,?>>`
      Specified by:
        `fmap` in interface `Monad<B,Fn1<A,?>>`
      Specified by:
        `fmap` in interface `MonadReader<A,B,Fn1<A,?>>`
      Specified by:
        `fmap` in interface `MonadRec<B,Fn1<A,?>>`
      Specified by:
        `fmap` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the return type of the next function to invoke
      Parameters:
        `f` - the function to invoke with this function's return value
      Returns:
        a function representing the composition of this function and f

    - #### pure

          default <C> Fn1<A,C> pure(C c)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<B,Fn1<A,?>>`
      Specified by:
        `pure` in interface `Monad<B,Fn1<A,?>>`
      Specified by:
        `pure` in interface `MonadReader<A,B,Fn1<A,?>>`
      Specified by:
        `pure` in interface `MonadRec<B,Fn1<A,?>>`
      Specified by:
        `pure` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the type of the returned applicative's parameter
      Parameters:
        `c` - the value
      Returns:
        an instance of this applicative over b

    - #### zip

          default <C> Fn1<A,C> zip(Applicative<Fn1<? super B,? extends C>,Fn1<A,?>> appFn)

      Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
      Specified by:
        `zip` in interface `Applicative<B,Fn1<A,?>>`
      Specified by:
        `zip` in interface `Monad<B,Fn1<A,?>>`
      Specified by:
        `zip` in interface `MonadReader<A,B,Fn1<A,?>>`
      Specified by:
        `zip` in interface `MonadRec<B,Fn1<A,?>>`
      Specified by:
        `zip` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### zip

          default <C> Fn1<A,C> zip(Fn2<A,B,C> appFn)

    - #### lazyZip

          default <C> Lazy<Fn1<A,C>> lazyZip(Lazy<? extends Applicative<Fn1<? super B,? extends C>,Fn1<A,?>>> lazyAppFn)

      Given a `lazy` instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports. This is useful for applicatives that support lazy evaluation and early termination.
      Specified by:
        `lazyZip` in interface `Applicative<B,Fn1<A,?>>`
      Specified by:
        `lazyZip` in interface `Monad<B,Fn1<A,?>>`
      Specified by:
        `lazyZip` in interface `MonadReader<A,B,Fn1<A,?>>`
      Specified by:
        `lazyZip` in interface `MonadRec<B,Fn1<A,?>>`
      Specified by:
        `lazyZip` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the resulting applicative parameter type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the mapped applicative
      See Also:
        `Maybe`, `Either`

    - #### trampolineM

          default <C> Fn1<A,C> trampolineM(Fn1<? super B,? extends MonadRec<RecursiveResult<B,C>,Fn1<A,?>>> fn)

      Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.

      Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.

      Specified by:
        `trampolineM` in interface `MonadRec<B,Fn1<A,?>>`
      Type Parameters:
        `C` - the ultimate resulting carrier type
      Parameters:
        `fn` - the function to internally trampoline
      Returns:
        the trampolined `MonadRec`
      See Also:
        `for a basic implementation`, `for a {@link CoProduct2 coproduct} implementation`, `for an implementation leveraging an already stack-safe {@link Monad#flatMap(Fn1)}`, `for a {@link MonadT monad transformer} implementation`

    - #### discardL

          default <C> Fn1<A,C> discardL(Applicative<C,Fn1<A,?>> appB)

      Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardL` in interface `Applicative<B,Fn1<A,?>>`
      Specified by:
        `discardL` in interface `Monad<B,Fn1<A,?>>`
      Specified by:
        `discardL` in interface `MonadReader<A,B,Fn1<A,?>>`
      Specified by:
        `discardL` in interface `MonadRec<B,Fn1<A,?>>`
      Specified by:
        `discardL` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          default <C> Fn1<A,B> discardR(Applicative<C,Fn1<A,?>> appB)

      Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`. This is generally useful for sequentially performing side-effects.
      Specified by:
        `discardR` in interface `Applicative<B,Fn1<A,?>>`
      Specified by:
        `discardR` in interface `Monad<B,Fn1<A,?>>`
      Specified by:
        `discardR` in interface `MonadReader<A,B,Fn1<A,?>>`
      Specified by:
        `discardR` in interface `MonadRec<B,Fn1<A,?>>`
      Specified by:
        `discardR` in interface `MonadWriter<A,B,Fn1<A,?>>`
      Type Parameters:
        `C` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### diMapL

          default <Z> Fn1<Z,B> diMapL(Fn1<? super Z,? extends A> fn)

      Contravariantly map over the argument to this function, producing a function that takes the new argument type, and produces the same result.
      Specified by:
        `diMapL` in interface `Cartesian<A,B,Fn1<?,?>>`
      Specified by:
        `diMapL` in interface `Cocartesian<A,B,Fn1<?,?>>`
      Specified by:
        `diMapL` in interface `Profunctor<A,B,Fn1<?,?>>`
      Type Parameters:
        `Z` - the new argument type
      Parameters:
        `fn` - the contravariant argument mapping function
      Returns:
        an `Fn1`<Z, B>

    - #### diMapR

          default <C> Fn1<A,C> diMapR(Fn1<? super B,? extends C> fn)

      Covariantly map over the return value of this function, producing a function that takes the same argument, and produces the new result type.
      Specified by:
        `diMapR` in interface `Cartesian<A,B,Fn1<?,?>>`
      Specified by:
        `diMapR` in interface `Cocartesian<A,B,Fn1<?,?>>`
      Specified by:
        `diMapR` in interface `Profunctor<A,B,Fn1<?,?>>`
      Type Parameters:
        `C` - the new result type
      Parameters:
        `fn` - the covariant result mapping function
      Returns:
        an `Fn1`<A, C>

    - #### diMap

          default <Z,C> Fn1<Z,C> diMap(Fn1<? super Z,? extends A> lFn,
                                       Fn1<? super B,? extends C> rFn)

      Exercise both `diMapL` and `diMapR` over this function in the same invocation.
      Specified by:
        `diMap` in interface `Cartesian<A,B,Fn1<?,?>>`
      Specified by:
        `diMap` in interface `Cocartesian<A,B,Fn1<?,?>>`
      Specified by:
        `diMap` in interface `Profunctor<A,B,Fn1<?,?>>`
      Type Parameters:
        `Z` - the new argument type
        `C` - the new result type
      Parameters:
        `lFn` - the contravariant argument mapping function
        `rFn` - the covariant result mapping function
      Returns:
        an `Fn1`<Z, C>

    - #### cartesian

          default <C> Fn1<Tuple2<C,A>,Tuple2<C,B>> cartesian()

      Pair a value with the input to this function, and preserve the paired value through to the output.
      Specified by:
        `cartesian` in interface `Cartesian<A,B,Fn1<?,?>>`
      Type Parameters:
        `C` - the paired value
      Returns:
        the strengthened `Fn1`

    - #### carry

          default Fn1<A,Tuple2<A,B>> carry()

      Pair the covariantly-positioned carrier type with the contravariantly-positioned carrier type. This can be thought of as "carrying" or "inspecting" the left parameter.
      Specified by:
        `carry` in interface `Cartesian<A,B,Fn1<?,?>>`
      Returns:
        the profunctor with the first parameter carried

    - #### cocartesian

          default <C> Fn1<Choice2<C,A>,Choice2<C,B>> cocartesian()

      Choose between either applying this function or returning back a different result altogether.
      Specified by:
        `cocartesian` in interface `Cocartesian<A,B,Fn1<?,?>>`
      Type Parameters:
        `C` - the potentially different result
      Returns:
        teh strengthened `Fn1`

    - #### choose

          default Fn1<A,Choice2<A,B>> choose()

      Choose between a successful result `b` or returning back the input, `a`.
      Specified by:
        `choose` in interface `Cocartesian<A,B,Fn1<?,?>>`
      Returns:
        an `Fn1` that chooses between its input (in case of failure) or its output.

    - #### contraMap

          default <Z> Fn1<Z,B> contraMap(Fn1<? super Z,? extends A> fn)

      Contravariantly map `A <- B`.
      Specified by:
        `contraMap` in interface `Cartesian<A,B,Fn1<?,?>>`
      Specified by:
        `contraMap` in interface `Cocartesian<A,B,Fn1<?,?>>`
      Specified by:
        `contraMap` in interface `Contravariant<A,Profunctor<?,B,Fn1<?,?>>>`
      Specified by:
        `contraMap` in interface `Profunctor<A,B,Fn1<?,?>>`
      Type Parameters:
        `Z` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        the mapped Contravariant functor instance

    - #### compose

          default <Y,Z> Fn2<Y,Z,B> compose(Fn2<? super Y,? super Z,? extends A> before)

      Right-to-left composition between different arity functions. Preserves highest arity in the return type.
      Type Parameters:
        `Y` - the resulting function's first argument type
        `Z` - the resulting function's second argument type
      Parameters:
        `before` - the function to pass its return value to this function's input
      Returns:
        an `Fn2`<Y, Z, B>

    - #### andThen

          default <C,D> Fn2<A,C,D> andThen(Fn2<? super B,? super C,? extends D> after)

      Left-to-right composition between different arity functions. Preserves highest arity in the return type.
      Type Parameters:
        `C` - the resulting function's second argument type
        `D` - the resulting function's return type
      Parameters:
        `after` - the function to invoke on this function's return value
      Returns:
        an `Fn2`<A, C, D>

    - #### fn1

          static <A,B> Fn1<A,B> fn1(Fn1<? super A,? extends B> fn)

      Static factory method for avoid explicit casting when using method references as `Fn1`s.
      Type Parameters:
        `A` - the input type
        `B` - the output type
      Parameters:
        `fn` - the function to adapt
      Returns:
        the `Fn1`

    - #### fromFunction

          static <A,B> Fn1<A,B> fromFunction(Function<? super A,? extends B> function)

      Static factory method for wrapping a java `Function` in an `Fn1`.
      Type Parameters:
        `A` - the input type
        `B` - the output type
      Parameters:
        `function` - the function
      Returns:
        the `Fn1`

    - #### pureFn1

          static <A> Pure<Fn1<A,?>> pureFn1()

      The canonical `Pure` instance for `Fn1`.
      Type Parameters:
        `A` - the input type
      Returns:
        the `Pure` instance