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 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 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.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<S,​T>
        Specified by:
        pure in interface Monad<S,​T>
        Specified by:
        pure in interface MonadRec<S,​T>
        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<S,​T>
        Specified by:
        flatMap in interface MonadRec<S,​T>
        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<S,​T>
        Specified by:
        fmap in interface Functor<S,​T>
        Specified by:
        fmap in interface Monad<S,​T>
        Specified by:
        fmap in interface MonadRec<S,​T>
        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<S,​T>
        Specified by:
        zip in interface Monad<S,​T>
        Specified by:
        zip in interface MonadRec<S,​T>
        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<S,​T>
        Specified by:
        lazyZip in interface Monad<S,​T>
        Specified by:
        lazyZip in interface MonadRec<S,​T>
        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<S,​T>
        Specified by:
        discardL in interface Monad<S,​T>
        Specified by:
        discardL in interface MonadRec<S,​T>
        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<S,​T>
        Specified by:
        discardR in interface Monad<S,​T>
        Specified by:
        discardR in interface MonadRec<S,​T>
        Type Parameters:
        U - the type of appB's parameter
        Parameters:
        appB - the other Applicative
        Returns:
        this Applicative
      • 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,​A>
        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,​A>
        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,​A>
        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,​T>
        Specified by:
        contraMap in interface Profunctor<S,​T,​A>
        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