com.jnape.palatable.lambda.optics

## Interface Prism<S,T,A,B>

- Type Parameters:
    `S` - the input that might fail to map to its output
    `T` - the guaranteed output
    `A` - the output that might fail to be produced
    `B` - the input that guarantees its output
  All Superinterfaces:
    Applicative<T,Prism<S,?,A,B>>, Contravariant<S,Profunctor<?,T,Prism<?,?,A,B>>>, Functor<T,Prism<S,?,A,B>>, Monad<T,Prism<S,?,A,B>>, MonadRec<T,Prism<S,?,A,B>>, Optic<Cocartesian<?,?,?>,Identity<?>,S,T,A,B>, Profunctor<S,T,Prism<?,?,A,B>>, ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>
  All Known Subinterfaces:
    Prism.Simple<S,A>
  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 Prism<S,T,A,B>
      extends ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>, MonadRec<T,Prism<S,?,A,B>>, Profunctor<S,T,Prism<?,?,A,B>>

  Prisms are `Isos` that can fail in one direction. Example:

       Prism<String, String, Integer, Integer> parseInt =
           prism(str -> Either.trying(() -> Integer.parseInt(str),
                                      constantly(str)),
                 Object::toString);

       String         str   = view(re(parseInt), 123); // "123"
       Maybe<Integer> works = view(pre(parseInt), "123"); // Just 123
       Maybe<Integer> fails = view(pre(parseInt), "foo"); // Nothing

  Note that because a `Prism` might fail in one direction, it cannot be immediately used for `viewing`; however, the combinators `re`, `pre`, and `matching` can all be used to provide the additional context to a `Prism` so it can be used for viewing.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Prism.Simple<S,A>` A convenience type with a simplified type signature for common `prism` with unified `S/T` and `A/B` types.

  - ### Method Summary

    All Methods Static Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <Z,C> Prism<S,T,Z,C>` | `andThen(ProtoOptic<? super Cocartesian<?,?,?>,A,B,Z,C> f)` Left-to-right composition of proto-optics.
    `default <CoP extends Profunctor<?,?,? extends Cocartesian<?,?,?>>,CoF extends Functor<?,? extends Identity<?>>,FB extends Functor<B,? extends CoF>,FT extends Functor<T,? extends CoF>,PAFB extends Profunctor<A,FB,? extends CoP>,PSFT extends Profunctor<S,FT,? extends CoP>> PSFT` | `apply(PAFB pafb)` The polymorphic arrow between profunctors in this optic interface.
    `default <R,U> Prism<R,U,A,B>` | `compose(ProtoOptic<? super Cocartesian<?,?,?>,R,U,S,T> g)` Right-to-Left composition of proto-optics.
    `default <R> Prism<R,T,A,B>` | `contraMap(Fn1<? super R,? extends S> fn)` Contravariantly map `A <- B`.
    `default <R,U> Prism<R,U,A,B>` | `diMap(Fn1<? super R,? extends S> lFn, Fn1<? super T,? extends U> rFn)` Dually map contravariantly over the left parameter and covariantly over the right parameter.
    `default <R> Prism<R,T,A,B>` | `diMapL(Fn1<? super R,? extends S> fn)` Contravariantly map over the left parameter.
    `default <U> Prism<S,U,A,B>` | `diMapR(Fn1<? super T,? extends U> fn)` Covariantly map over the right parameter.
    `default <U> Prism<S,U,A,B>` | `discardL(Applicative<U,Prism<S,?,A,B>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `default <U> Prism<S,T,A,B>` | `discardR(Applicative<U,Prism<S,?,A,B>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `default <U> Prism<S,U,A,B>` | `flatMap(Fn1<? super T,? extends Monad<U,Prism<S,?,A,B>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `default <U> Prism<S,U,A,B>` | `fmap(Fn1<? super T,? extends U> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `static <S,A,B> Prism<S,S,A,B>` | `fromPartial(Fn1<? super S,? extends A> partialSa, Fn1<? super B,? extends S> bs)` Static factory method for creating a `Prism` from a partial function `S -> A` and a total function `B -> S`.
    `default <U> Lazy<Prism<S,U,A,B>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super T,? extends U>,Prism<S,?,A,B>>> 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> Prism<S,T,C,B>` | `mapA(Fn1<? super A,? extends C> fn)` Covariantly map `A` to `C`, yielding a new optic.
    `default <Z> Prism<S,T,A,Z>` | `mapB(Fn1<? super Z,? extends B> fn)` Contravariantly map `B` to `Z`, yielding a new optic.
    `default <R> Prism<R,T,A,B>` | `mapS(Fn1<? super R,? extends S> fn)` Contravariantly map `S` to `R`, yielding a new optic.
    `default <U> Prism<S,U,A,B>` | `mapT(Fn1<? super T,? extends U> fn)` Covariantly map `T` to `U`, yielding a new optic.
    `static <S,T,A,B> Prism<S,T,A,B>` | `prism(Fn1<? super S,? extends CoProduct2<T,A,?>> sta, Fn1<? super B,? extends T> bt)` Static factory method for creating a `Prism` given a mapping from `S -> `Either`<T, A>` and a mapping from `B -> T`.
    `static <S,T,A,B> Prism<S,T,A,B>` | `prism(Optic<? super Cocartesian<?,?,?>,? super Functor<?,?>,S,T,A,B> optic)` Promote an `Optic` with compatible bounds to an `Prism`.
    `static <S,T,A,B> Prism<S,T,A,B>` | `prism(ProtoOptic<? super Cocartesian<?,?,?>,S,T,A,B> protoOptic)` Promote a `ProtoOptic` with compatible bounds to an `Prism`.
    `default <U> Prism<S,U,A,B>` | `pure(U u)` Lift the value `b` into this applicative functor.
    `static <S,A,B> Pure<Prism<S,?,A,B>>` | `purePrism()` The canonical `Pure` instance for `Prism`.
    `static <S,A> Prism.Simple<S,A>` | `simplePrism(Fn1<? super S,? extends Maybe<A>> sMaybeA, Fn1<? super A,? extends S> as)` Static factory method for creating a simple `Prism` from a function and its potentially failing inverse.
    `default <U> Prism<S,U,A,B>` | `trampolineM(Fn1<? super T,? extends MonadRec<RecursiveResult<T,U>,Prism<S,?,A,B>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `default Tuple2<Fn1<? super B,? extends T>,Fn1<? super S,? extends Either<T,A>>>` | `unPrism()` Recover the two mappings encapsulated by this `Prism` by sending it through a `Market`.
    `default <U> Prism<S,U,A,B>` | `zip(Applicative<Fn1<? super T,? extends U>,Prism<S,?,A,B>> appFn)` Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.

    - ### Methods inherited from interface com.jnape.palatable.lambda.optics.ProtoOptic

      `toOptic`

    - ### Methods inherited from interface com.jnape.palatable.lambda.optics.Optic

      `andThen, compose, monomorphize, optic, reframe`

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

      `join`

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

      `coerce`

- - ### Method Detail

    - #### unPrism

          default Tuple2<Fn1<? super B,? extends T>,Fn1<? super S,? extends Either<T,A>>> unPrism()

      Recover the two mappings encapsulated by this `Prism` by sending it through a `Market`.
      Returns:
        a `tuple` of the two mappings encapsulated by this `Prism`

    - #### apply

          default <CoP extends Profunctor<?,?,? extends Cocartesian<?,?,?>>,CoF extends Functor<?,? extends Identity<?>>,FB extends Functor<B,? extends CoF>,FT extends Functor<T,? extends CoF>,PAFB extends Profunctor<A,FB,? extends CoP>,PSFT extends Profunctor<S,FT,? extends CoP>> PSFT apply(PAFB pafb)

      The polymorphic arrow between profunctors in this optic interface.
      Specified by:
        `apply` in interface `Optic<Cocartesian<?,?,?>,Identity<?>,S,T,A,B>`
      Specified by:
        `apply` in interface `ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>`
      Type Parameters:
        `CoP` - the profunctor type constraint witnessed by the application of this optic
        `CoF` - the functor type constraint witnessed by the application of this optic
        `FB` - the covariant parameter type of the input profunctor
        `FT` - the covariant parameter type of the output profunctor
        `PAFB` - the full input type
        `PSFT` - the full output type
      Parameters:
        `pafb` - the input
      Returns:
        the output profunctor

    - #### andThen

          default <Z,C> Prism<S,T,Z,C> andThen(ProtoOptic<? super Cocartesian<?,?,?>,A,B,Z,C> f)

      Left-to-right composition of proto-optics. Requires compatibility between `S` and `T`.
      Specified by:
        `andThen` in interface `ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>`
      Type Parameters:
        `Z` - the new left side of the input profunctor
        `C` - the new right side's functor embedding of the input profunctor
      Parameters:
        `f` - the other proto-optic
      Returns:
        the composed proto-optic

    - #### compose

          default <R,U> Prism<R,U,A,B> compose(ProtoOptic<? super Cocartesian<?,?,?>,R,U,S,T> g)

      Right-to-Left composition of proto-optics. Requires compatibility between `A` and `B`.
      Specified by:
        `compose` in interface `ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>`
      Type Parameters:
        `R` - the new left side of the output profunctor
        `U` - the new right side's functor embedding of the output profunctor
      Parameters:
        `g` - the other proto-optic
      Returns:
        the composed proto-optic

    - #### mapS

          default <R> Prism<R,T,A,B> mapS(Fn1<? super R,? extends S> fn)

      Contravariantly map `S` to `R`, yielding a new optic.
      Specified by:
        `mapS` in interface `Optic<Cocartesian<?,?,?>,Identity<?>,S,T,A,B>`
      Specified by:
        `mapS` in interface `ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>`
      Type Parameters:
        `R` - the new left side of the output profunctor
      Parameters:
        `fn` - the mapping function
      Returns:
        the new optic

    - #### mapT

          default <U> Prism<S,U,A,B> mapT(Fn1<? super T,? extends U> fn)

      Covariantly map `T` to `U`, yielding a new optic.
      Specified by:
        `mapT` in interface `Optic<Cocartesian<?,?,?>,Identity<?>,S,T,A,B>`
      Specified by:
        `mapT` in interface `ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>`
      Type Parameters:
        `U` - the new right side's functor embedding of the output profunctor
      Parameters:
        `fn` - the mapping function
      Returns:
        the new optic

    - #### mapA

          default <C> Prism<S,T,C,B> mapA(Fn1<? super A,? extends C> fn)

      Covariantly map `A` to `C`, yielding a new optic.
      Specified by:
        `mapA` in interface `Optic<Cocartesian<?,?,?>,Identity<?>,S,T,A,B>`
      Specified by:
        `mapA` in interface `ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>`
      Type Parameters:
        `C` - the new left side of the input profunctor
      Parameters:
        `fn` - the mapping function
      Returns:
        the new optic

    - #### mapB

          default <Z> Prism<S,T,A,Z> mapB(Fn1<? super Z,? extends B> fn)

      Contravariantly map `B` to `Z`, yielding a new optic.
      Specified by:
        `mapB` in interface `Optic<Cocartesian<?,?,?>,Identity<?>,S,T,A,B>`
      Specified by:
        `mapB` in interface `ProtoOptic<Cocartesian<?,?,?>,S,T,A,B>`
      Type Parameters:
        `Z` - the new right side's functor embedding of the input profunctor
      Parameters:
        `fn` - the mapping function
      Returns:
        the new optic

    - #### pure

          default <U> Prism<S,U,A,B> pure(U u)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<T,Prism<S,?,A,B>>`
      Specified by:
        `pure` in interface `Monad<T,Prism<S,?,A,B>>`
      Specified by:
        `pure` in interface `MonadRec<T,Prism<S,?,A,B>>`
      Type Parameters:
        `U` - the type of the returned applicative's parameter
      Parameters:
        `u` - the value
      Returns:
        an instance of this applicative over b

    - #### flatMap

          default <U> Prism<S,U,A,B> flatMap(Fn1<? super T,? extends Monad<U,Prism<S,?,A,B>>> f)

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

    - #### fmap

          default <U> Prism<S,U,A,B> fmap(Fn1<? super T,? extends U> fn)

      Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.
      Specified by:
        `fmap` in interface `Applicative<T,Prism<S,?,A,B>>`
      Specified by:
        `fmap` in interface `Functor<T,Prism<S,?,A,B>>`
      Specified by:
        `fmap` in interface `Monad<T,Prism<S,?,A,B>>`
      Specified by:
        `fmap` in interface `MonadRec<T,Prism<S,?,A,B>>`
      Type Parameters:
        `U` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### zip

          default <U> Prism<S,U,A,B> zip(Applicative<Fn1<? super T,? extends U>,Prism<S,?,A,B>> 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<T,Prism<S,?,A,B>>`
      Specified by:
        `zip` in interface `Monad<T,Prism<S,?,A,B>>`
      Specified by:
        `zip` in interface `MonadRec<T,Prism<S,?,A,B>>`
      Type Parameters:
        `U` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          default <U> Lazy<Prism<S,U,A,B>> lazyZip(Lazy<? extends Applicative<Fn1<? super T,? extends U>,Prism<S,?,A,B>>> 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<T,Prism<S,?,A,B>>`
      Specified by:
        `lazyZip` in interface `Monad<T,Prism<S,?,A,B>>`
      Specified by:
        `lazyZip` in interface `MonadRec<T,Prism<S,?,A,B>>`
      Type Parameters:
        `U` - the resulting applicative parameter type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the mapped applicative
      See Also:
        `Maybe`, `Either`

    - #### discardL

          default <U> Prism<S,U,A,B> discardL(Applicative<U,Prism<S,?,A,B>> 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<T,Prism<S,?,A,B>>`
      Specified by:
        `discardL` in interface `Monad<T,Prism<S,?,A,B>>`
      Specified by:
        `discardL` in interface `MonadRec<T,Prism<S,?,A,B>>`
      Type Parameters:
        `U` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          default <U> Prism<S,T,A,B> discardR(Applicative<U,Prism<S,?,A,B>> 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<T,Prism<S,?,A,B>>`
      Specified by:
        `discardR` in interface `Monad<T,Prism<S,?,A,B>>`
      Specified by:
        `discardR` in interface `MonadRec<T,Prism<S,?,A,B>>`
      Type Parameters:
        `U` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### trampolineM

          default <U> Prism<S,U,A,B> trampolineM(Fn1<? super T,? extends MonadRec<RecursiveResult<T,U>,Prism<S,?,A,B>>> 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<T,Prism<S,?,A,B>>`
      Type Parameters:
        `U` - 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`

    - #### diMap

          default <R,U> Prism<R,U,A,B> diMap(Fn1<? super R,? extends S> lFn,
                                             Fn1<? super T,? extends U> rFn)

      Dually map contravariantly over the left parameter and covariantly over the right parameter. This is isomorphic to `diMapL(lFn).diMapR(rFn)`.
      Specified by:
        `diMap` in interface `Profunctor<S,T,Prism<?,?,A,B>>`
      Type Parameters:
        `R` - the new left parameter type
        `U` - the new right parameter type
      Parameters:
        `lFn` - the left parameter mapping function
        `rFn` - the right parameter mapping function
      Returns:
        a profunctor over Z (the new left parameter type) and C (the new right parameter type)

    - #### diMapL

          default <R> Prism<R,T,A,B> diMapL(Fn1<? super R,? extends S> fn)

      Contravariantly map over the left parameter.
      Specified by:
        `diMapL` in interface `Profunctor<S,T,Prism<?,?,A,B>>`
      Type Parameters:
        `R` - the new left parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a profunctor over Z (the new left parameter type) and C (the same right parameter type)

    - #### diMapR

          default <U> Prism<S,U,A,B> diMapR(Fn1<? super T,? extends U> fn)

      Covariantly map over the right parameter. For all profunctors that are also functors, it should hold that `diMapR(f) == fmap(f)`.
      Specified by:
        `diMapR` in interface `Profunctor<S,T,Prism<?,?,A,B>>`
      Type Parameters:
        `U` - the new right parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a profunctor over A (the same left parameter type) and C (the new right parameter type)

    - #### contraMap

          default <R> Prism<R,T,A,B> contraMap(Fn1<? super R,? extends S> fn)

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

    - #### prism

          static <S,T,A,B> Prism<S,T,A,B> prism(Fn1<? super S,? extends CoProduct2<T,A,?>> sta,
                                                Fn1<? super B,? extends T> bt)

      Static factory method for creating a `Prism` given a mapping from `S -> `Either`<T, A>` and a mapping from `B -> T`.
      Type Parameters:
        `S` - the input that might fail to map to its output
        `T` - the guaranteed output
        `A` - the output that might fail to be produced
        `B` - the input that guarantees its output
      Parameters:
        `sta` - the mapping from S -> `Either`<T, A>
        `bt` - the mapping from B -> T
      Returns:
        the `Prism`

    - #### prism

          static <S,T,A,B> Prism<S,T,A,B> prism(ProtoOptic<? super Cocartesian<?,?,?>,S,T,A,B> protoOptic)

      Promote a `ProtoOptic` with compatible bounds to an `Prism`.
      Type Parameters:
        `S` - the input that might fail to map to its output
        `T` - the guaranteed output
        `A` - the output that might fail to be produced
        `B` - the input that guarantees its output
      Parameters:
        `protoOptic` - the `ProtoOptic`
      Returns:
        the `Prism`

    - #### prism

          static <S,T,A,B> Prism<S,T,A,B> prism(Optic<? super Cocartesian<?,?,?>,? super Functor<?,?>,S,T,A,B> optic)

      Promote an `Optic` with compatible bounds to an `Prism`. Note that because the `Optic` must guarantee an unbounded `Functor` constraint in order to satisfy any future covariant constraint, the resulting `prism's` `toOptic` method will never need to consult its given `lifting` function.
      Type Parameters:
        `S` - the input that might fail to map to its output
        `T` - the guaranteed output
        `A` - the output that might fail to be produced
        `B` - the input that guarantees its output
      Parameters:
        `optic` - the `Optic`
      Returns:
        the `Prism`

    - #### simplePrism

          static <S,A> Prism.Simple<S,A> simplePrism(Fn1<? super S,? extends Maybe<A>> sMaybeA,
                                                     Fn1<? super A,? extends S> as)

      Static factory method for creating a simple `Prism` from a function and its potentially failing inverse.
      Type Parameters:
        `S` - the input that might fail to map to its output and the guaranteed output from the other direction
        `A` - the output that might fail to be produced and the input that guarantees its output in the other direction
      Parameters:
        `sMaybeA` - a partial mapping from `S -> A`
        `as` - a total mapping from `A -> S`
      Returns:
        the `simple prism`

    - #### fromPartial

          static <S,A,B> Prism<S,S,A,B> fromPartial(Fn1<? super S,? extends A> partialSa,
                                                    Fn1<? super B,? extends S> bs)

      Static factory method for creating a `Prism` from a partial function `S -> A` and a total function `B -> S`.
      Type Parameters:
        `S` - the input that might fail to map to its output and the guaranteed output from the other direction
        `A` - the output that might fail to be produced
        `B` - the input that guarantees its output in the other direction
      Parameters:
        `partialSa` - the partial direction
        `bs` - the reverse total direction
      Returns:
        the `Prism`

    - #### purePrism

          static <S,A,B> Pure<Prism<S,?,A,B>> purePrism()

      The canonical `Pure` instance for `Prism`.
      Type Parameters:
        `S` - the input that might fail to map to its output
        `A` - the output that might fail to be produced
        `B` - the input that guarantees its output
      Returns:
        the `Pure` instance