Class Either<L,​R>

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Either.Left<L,​R>  
      private static class  Either.Right<L,​R>  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Either()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      <L2,​R2>
      Either<L2,​R2>
      biMap​(Fn1<? super L,​? extends L2> leftFn, Fn1<? super R,​? extends R2> rightFn)
      Dually map covariantly over both the left and right parameters.
      <L2> Either<L2,​R> biMapL​(Fn1<? super L,​? extends L2> fn)
      Covariantly map over the left parameter.
      <R2> Either<L,​R2> biMapR​(Fn1<? super R,​? extends R2> fn)
      Covariantly map over the right parameter.
      Either<L,​R> catchError​(Fn1<? super L,​? extends Monad<R,​Either<L,​?>>> recoveryFn)
      Catch any thrown errors inside the Monad and resume normal operations.
      <R2> Either<L,​R2> discardL​(Applicative<R2,​Either<L,​?>> appB)
      Sequence both this Applicative and appB, discarding this Applicative's result and returning appB.
      <R2> Either<L,​R> discardR​(Applicative<R2,​Either<L,​?>> appB)
      Sequence both this Applicative and appB, discarding appB's result and returning this Applicative.
      <C> Choice3<L,​R,​C> diverge()
      Diverge this coproduct by introducing another possible type that it could represent.
      Either<L,​R> filter​(Fn1<? super R,​? extends java.lang.Boolean> pred, Fn0<L> leftFn0)
      If this is a right value, apply pred to it.
      Either<L,​R> filter​(Fn1<? super R,​? extends java.lang.Boolean> pred, Fn1<? super R,​? extends L> leftFn)
      If this is a right value, apply pred to it.
      <R2> Either<L,​R2> flatMap​(Fn1<? super R,​? extends Monad<R2,​Either<L,​?>>> rightFn)
      If a right value, unwrap it and apply it to rightFn, returning the resulting Either<L ,R>.
      <R2> Either<L,​R2> fmap​(Fn1<? super R,​? extends R2> fn)
      Covariantly transmute this functor's parameter using the given mapping function.
      L forfeit​(Fn1<? super R,​? extends L> forfeitFn)
      Inverse of recover.
      static <L,​R>
      Either<L,​R>
      fromMaybe​(Maybe<R> maybe, Fn0<L> leftFn0)
      Convert a Maybe<R> into an Either<L, R>, supplying the left value from leftFn in the case of Maybe.nothing().
      Either<R,​L> invert()
      Swap the type parameters.
      <R2> Lazy<Either<L,​R2>> lazyZip​(Lazy<? extends Applicative<Fn1<? super R,​? extends R2>,​Either<L,​?>>> 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.
      static <L,​R>
      Either<L,​R>
      left​(L l)
      Static factory method for creating a left value.
      abstract <V> V match​(Fn1<? super L,​? extends V> leftFn, Fn1<? super R,​? extends V> rightFn)
      Given two mapping functions (one from an L to a V, one from an R to a V), unwrap the value stored in this Either, apply the appropriate mapping function, and return the result.
      Either<L,​R> merge​(Fn2<? super L,​? super L,​? extends L> leftFn, Fn2<? super R,​? super R,​? extends R> rightFn, Either<L,​R>... others)
      Given two binary operators over L and R, merge multiple Either<L, R>s into a single Either<L, R>.
      R or​(R defaultValue)
      Return the value wrapped by this Either if it's a right value; otherwise, return defaultValue.
      <T extends java.lang.Throwable>
      R
      orThrow​(Fn1<? super L,​? extends T> throwableFn)
      Return the wrapped value if this is a right; otherwise, map the wrapped left value to a T and throw it.
      Either<L,​R> peek​(Fn1<? super L,​? extends IO<?>> leftEffect, Fn1<? super R,​? extends IO<?>> rightEffect)
      Deprecated.
      in favor of matching into an IO and explicitly running it
      Either<L,​R> peek​(Fn1<? super R,​? extends IO<?>> effect)
      Deprecated.
      in favor of matching into an IO and explicitly running it
      <R2> Either<L,​R2> pure​(R2 r2)
      Lift the value b into this applicative functor.
      static <L> Pure<Either<L,​?>> pureEither()
      The canonical Pure instance for Either.
      R recover​(Fn1<? super L,​? extends R> recoveryFn)
      "Recover" from a left value by applying a recoveryFn to the wrapped value and returning it in the case of a left value; otherwise, return the wrapped right value.
      static <L,​R>
      Either<L,​R>
      right​(R r)
      Static factory method for creating a right value.
      Either<L,​R> throwError​(L l)
      Throw an error value of type E into the monad.
      Maybe<R> toMaybe()
      In the left case, returns a Maybe.nothing(); otherwise, returns Maybe.maybe(A) around the right value.
      <B> Either<L,​B> trampolineM​(Fn1<? super R,​? extends MonadRec<RecursiveResult<R,​B>,​Either<L,​?>>> fn)
      Given some operation yielding a RecursiveResult inside this MonadRec, internally trampoline the operation until it yields a termination instruction.
      <R2,​App extends Applicative<?,​App>,​TravB extends Traversable<R2,​Either<L,​?>>,​AppTrav extends Applicative<TravB,​App>>
      AppTrav
      traverse​(Fn1<? super R,​? extends Applicative<R2,​App>> fn, Fn1<? super TravB,​? extends AppTrav> pure)
      Apply fn to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
      static <R> Either<java.lang.Throwable,​R> trying​(Fn0<? extends R> fn0)
      Attempt to execute the Fn0, returning its result in a right value.
      static <L,​R>
      Either<L,​R>
      trying​(Fn0<? extends R> fn0, Fn1<? super java.lang.Throwable,​? extends L> leftFn)
      Attempt to execute the Fn0, returning its result in a right value.
      static Either<java.lang.Throwable,​Unit> trying​(SideEffect sideEffect)
      Attempt to execute the SideEffect, returning Unit in a right value.
      static <L> Either<L,​Unit> trying​(SideEffect sideEffect, Fn1<? super java.lang.Throwable,​? extends L> leftFn)
      Attempt to execute the SideEffect, returning Unit in a right value.
      <R2> Either<L,​R2> zip​(Applicative<Fn1<? super R,​? extends R2>,​Either<L,​?>> 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 class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

        coerce
    • Constructor Detail

      • Either

        private Either()
    • Method Detail

      • or

        public final R or​(R defaultValue)
        Return the value wrapped by this Either if it's a right value; otherwise, return defaultValue.
        Parameters:
        defaultValue - the value to return if this is a left
        Returns:
        the value wrapped by this Either if right; otherwise, defaultValue
      • recover

        public final R recover​(Fn1<? super L,​? extends R> recoveryFn)
        "Recover" from a left value by applying a recoveryFn to the wrapped value and returning it in the case of a left value; otherwise, return the wrapped right value.
        Parameters:
        recoveryFn - a function from L to R
        Returns:
        either the wrapped value (if right) or the result of the left value applied to recoveryFn
      • forfeit

        public final L forfeit​(Fn1<? super R,​? extends L> forfeitFn)
        Inverse of recover. If this is a right value, apply the wrapped value to forfeitFn and return it; otherwise, return the wrapped left value.
        Parameters:
        forfeitFn - a function from R to L
        Returns:
        either the wrapped value (if left) or the result of the right value applied to forfeitFn
      • orThrow

        public final <T extends java.lang.Throwable> R orThrow​(Fn1<? super L,​? extends T> throwableFn)
                                                        throws T extends java.lang.Throwable
        Return the wrapped value if this is a right; otherwise, map the wrapped left value to a T and throw it.
        Type Parameters:
        T - the left parameter type (the throwable type)
        Parameters:
        throwableFn - a function from L to T
        Returns:
        the wrapped value if this is a right
        Throws:
        T - the result of applying the wrapped left value to throwableFn, if this is a left
        T extends java.lang.Throwable
      • filter

        public final Either<L,​R> filter​(Fn1<? super R,​? extends java.lang.Boolean> pred,
                                              Fn0<L> leftFn0)
        If this is a right value, apply pred to it. If the result is true, return the same value; otherwise, return the result of leftSupplier wrapped as a left value.

        If this is a left value, return it.

        Parameters:
        pred - the predicate to apply to a right value
        leftFn0 - the supplier of a left value if pred fails
        Returns:
        this if a left value or a right value that pred matches; otherwise, the result of leftSupplier wrapped in a left
      • filter

        public final Either<L,​R> filter​(Fn1<? super R,​? extends java.lang.Boolean> pred,
                                              Fn1<? super R,​? extends L> leftFn)
        If this is a right value, apply pred to it. If the result is true, return the same value; otherwise, return the results of applying the right value to leftFn wrapped as a left value.
        Parameters:
        pred - the predicate to apply to a right value
        leftFn - the function from the right value to a left value if pred fails
        Returns:
        this is a left value or a right value that pred matches; otherwise, the result of leftFn applied to the right value, wrapped in a left
      • flatMap

        public <R2> Either<L,​R2> flatMap​(Fn1<? super R,​? extends Monad<R2,​Either<L,​?>>> rightFn)
        If a right value, unwrap it and apply it to rightFn, returning the resulting Either<L ,R>. Otherwise, return the left value.

        Note that because this monadic form of flatMap only supports mapping over a theoretical right value, the resulting Either must be invariant on the same left value to flatten properly.

        Specified by:
        flatMap in interface Monad<L,​R>
        Specified by:
        flatMap in interface MonadError<L,​R,​Either<L,​?>>
        Specified by:
        flatMap in interface MonadRec<L,​R>
        Type Parameters:
        R2 - the new right parameter type
        Parameters:
        rightFn - the function to apply to a right value
        Returns:
        the Either resulting from applying rightFn to this right value, or this left value if left
      • invert

        public final Either<R,​L> invert()
        Description copied from interface: CoProduct2
        Swap the type parameters.
        Specified by:
        invert in interface CoProduct2<L,​R,​Either<L,​R>>
        Returns:
        The inverted coproduct
      • merge

        @SafeVarargs
        public final Either<L,​R> merge​(Fn2<? super L,​? super L,​? extends L> leftFn,
                                             Fn2<? super R,​? super R,​? extends R> rightFn,
                                             Either<L,​R>... others)
        Given two binary operators over L and R, merge multiple Either<L, R>s into a single Either<L, R>. Note that merge biases towards left values; that is, if any left value exists, the result will be a left value, such that only unanimous right values result in an ultimate right value.
        Parameters:
        leftFn - the binary operator for L
        rightFn - the binary operator for R
        others - the other Eithers to merge into this one
        Returns:
        the merged Either
      • peek

        @Deprecated
        public Either<L,​R> peek​(Fn1<? super R,​? extends IO<?>> effect)
        Deprecated.
        in favor of matching into an IO and explicitly running it
        Perform side-effects against a wrapped right value, returning back the Either unaltered.
        Parameters:
        effect - the effecting consumer
        Returns:
        the Either, unaltered
      • peek

        @Deprecated
        public Either<L,​R> peek​(Fn1<? super L,​? extends IO<?>> leftEffect,
                                      Fn1<? super R,​? extends IO<?>> rightEffect)
        Deprecated.
        in favor of matching into an IO and explicitly running it
        Perform side-effects against a wrapped right or left value, returning back the Either unaltered.
        Parameters:
        leftEffect - the effecting consumer for left values
        rightEffect - the effecting consumer for right values
        Returns:
        the Either, unaltered
      • match

        public abstract <V> V match​(Fn1<? super L,​? extends V> leftFn,
                                    Fn1<? super R,​? extends V> rightFn)
        Given two mapping functions (one from an L to a V, one from an R to a V), unwrap the value stored in this Either, apply the appropriate mapping function, and return the result.
        Specified by:
        match in interface CoProduct2<L,​R,​Either<L,​R>>
        Type Parameters:
        V - the result type
        Parameters:
        leftFn - the left value mapping function
        rightFn - the right value mapping function
        Returns:
        the result of applying the appropriate mapping function to the wrapped value
      • diverge

        public <C> Choice3<L,​R,​C> diverge()
        Diverge this coproduct by introducing another possible type that it could represent. As no morphisms can be provided mapping current types to the new type, this operation merely acts as a convenience method to allow the use of a more convergent coproduct with a more divergent one; that is, if a CoProduct3<String, Integer, Boolean> is expected, a CoProduct2<String, Integer> should suffice.

        Generally, we use inheritance to make this a non-issue; however, with coproducts of differing magnitudes, we cannot guarantee variance compatibility in one direction conveniently at construction time, and in the other direction, at all. A CoProduct2 could not be a CoProduct3 without specifying all type parameters that are possible for a CoProduct3 - more specifically, the third possible type - which is not necessarily known at construction time, or even useful if never used in the context of a CoProduct3. The inverse inheritance relationship - CoProduct3 < CoProduct2 - is inherently unsound, as a CoProduct3 cannot correctly implement CoProduct2.match(com.jnape.palatable.lambda.functions.Fn1<? super A, ? extends R>, com.jnape.palatable.lambda.functions.Fn1<? super B, ? extends R>), given that the third type C is always possible.

        For this reason, there is a diverge method supported between all CoProduct types of single magnitude difference.

        Specified by:
        diverge in interface CoProduct2<L,​R,​Either<L,​R>>
        Type Parameters:
        C - the additional possible type of this coproduct
        Returns:
        a CoProduct3<A, B, C>
      • fmap

        public final <R2> Either<L,​R2> fmap​(Fn1<? super R,​? extends R2> 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<L,​R>
        Specified by:
        fmap in interface Functor<L,​R>
        Specified by:
        fmap in interface Monad<L,​R>
        Specified by:
        fmap in interface MonadError<L,​R,​Either<L,​?>>
        Specified by:
        fmap in interface MonadRec<L,​R>
        Specified by:
        fmap in interface Traversable<L,​R>
        Type Parameters:
        R2 - the new parameter type
        Parameters:
        fn - the mapping function
        Returns:
        a functor over B (the new parameter type)
      • biMapL

        public final <L2> Either<L2,​R> biMapL​(Fn1<? super L,​? extends L2> fn)
        Covariantly map over the left parameter.
        Specified by:
        biMapL in interface Bifunctor<L,​R,​Either<?,​?>>
        Specified by:
        biMapL in interface BoundedBifunctor<L,​R,​java.lang.Object,​java.lang.Object,​Either<?,​?>>
        Type Parameters:
        L2 - the new left parameter type
        Parameters:
        fn - the mapping function
        Returns:
        a bifunctor over C (the new left parameter) and B (the same right parameter)
      • biMapR

        public final <R2> Either<L,​R2> biMapR​(Fn1<? super R,​? extends R2> fn)
        Covariantly map over the right parameter. For all bifunctors that are also functors, it should hold that biMapR(f) == fmap(f).
        Specified by:
        biMapR in interface Bifunctor<L,​R,​Either<?,​?>>
        Specified by:
        biMapR in interface BoundedBifunctor<L,​R,​java.lang.Object,​java.lang.Object,​Either<?,​?>>
        Type Parameters:
        R2 - the new right parameter type
        Parameters:
        fn - the mapping function
        Returns:
        a bifunctor over A (the same left parameter) and C (the new right parameter)
      • biMap

        public final <L2,​R2> Either<L2,​R2> biMap​(Fn1<? super L,​? extends L2> leftFn,
                                                             Fn1<? super R,​? extends R2> rightFn)
        Dually map covariantly over both the left and right parameters. This is isomorphic to biMapL(lFn).biMapR(rFn).
        Specified by:
        biMap in interface Bifunctor<L,​R,​Either<?,​?>>
        Specified by:
        biMap in interface BoundedBifunctor<L,​R,​java.lang.Object,​java.lang.Object,​Either<?,​?>>
        Type Parameters:
        L2 - the new left parameter type
        R2 - the new right parameter type
        Parameters:
        leftFn - the left parameter mapping function
        rightFn - the right parameter mapping function
        Returns:
        a bifunctor over C (the new left parameter type) and D (the new right parameter type)
      • pure

        public final <R2> Either<L,​R2> pure​(R2 r2)
        Lift the value b into this applicative functor.
        Specified by:
        pure in interface Applicative<L,​R>
        Specified by:
        pure in interface Monad<L,​R>
        Specified by:
        pure in interface MonadError<L,​R,​Either<L,​?>>
        Specified by:
        pure in interface MonadRec<L,​R>
        Type Parameters:
        R2 - the type of the returned applicative's parameter
        Parameters:
        r2 - the value
        Returns:
        an instance of this applicative over b
      • zip

        public final <R2> Either<L,​R2> zip​(Applicative<Fn1<? super R,​? extends R2>,​Either<L,​?>> 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<L,​R>
        Specified by:
        zip in interface Monad<L,​R>
        Specified by:
        zip in interface MonadError<L,​R,​Either<L,​?>>
        Specified by:
        zip in interface MonadRec<L,​R>
        Type Parameters:
        R2 - the resulting applicative parameter type
        Parameters:
        appFn - the other applicative instance
        Returns:
        the mapped applicative
      • lazyZip

        public <R2> Lazy<Either<L,​R2>> lazyZip​(Lazy<? extends Applicative<Fn1<? super R,​? extends R2>,​Either<L,​?>>> 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<L,​R>
        Specified by:
        lazyZip in interface Monad<L,​R>
        Specified by:
        lazyZip in interface MonadError<L,​R,​Either<L,​?>>
        Specified by:
        lazyZip in interface MonadRec<L,​R>
        Type Parameters:
        R2 - the resulting applicative parameter type
        Parameters:
        lazyAppFn - the lazy other applicative instance
        Returns:
        the mapped applicative
        See Also:
        Maybe, Either
      • discardL

        public final <R2> Either<L,​R2> discardL​(Applicative<R2,​Either<L,​?>> 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<L,​R>
        Specified by:
        discardL in interface Monad<L,​R>
        Specified by:
        discardL in interface MonadError<L,​R,​Either<L,​?>>
        Specified by:
        discardL in interface MonadRec<L,​R>
        Type Parameters:
        R2 - the type of the returned Applicative's parameter
        Parameters:
        appB - the other Applicative
        Returns:
        appB
      • discardR

        public final <R2> Either<L,​R> discardR​(Applicative<R2,​Either<L,​?>> 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<L,​R>
        Specified by:
        discardR in interface Monad<L,​R>
        Specified by:
        discardR in interface MonadError<L,​R,​Either<L,​?>>
        Specified by:
        discardR in interface MonadRec<L,​R>
        Type Parameters:
        R2 - the type of appB's parameter
        Parameters:
        appB - the other Applicative
        Returns:
        this Applicative
      • traverse

        public final <R2,​App extends Applicative<?,​App>,​TravB extends Traversable<R2,​Either<L,​?>>,​AppTrav extends Applicative<TravB,​App>> AppTrav traverse​(Fn1<? super R,​? extends Applicative<R2,​App>> fn,
                                                                                                                                                                                                     Fn1<? super TravB,​? extends AppTrav> pure)
        Apply fn to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
        Specified by:
        traverse in interface Traversable<L,​R>
        Type Parameters:
        R2 - the resulting element type
        App - the result applicative type
        TravB - this Traversable instance over B
        AppTrav - the full inferred resulting type from the traversal
        Parameters:
        fn - the function to apply
        pure - the applicative pure function
        Returns:
        the traversed Traversable, wrapped inside an applicative
      • toMaybe

        public final Maybe<R> toMaybe()
        In the left case, returns a Maybe.nothing(); otherwise, returns Maybe.maybe(A) around the right value.
        Returns:
        Maybe the right value
      • fromMaybe

        public static <L,​R> Either<L,​R> fromMaybe​(Maybe<R> maybe,
                                                              Fn0<L> leftFn0)
        Convert a Maybe<R> into an Either<L, R>, supplying the left value from leftFn in the case of Maybe.nothing().
        Type Parameters:
        L - the left parameter type
        R - the right parameter type
        Parameters:
        maybe - the maybe
        leftFn0 - the supplier to use for left values
        Returns:
        a right value of the contained maybe value, or a left value of leftFn's result
      • trying

        public static <L,​R> Either<L,​R> trying​(Fn0<? extends R> fn0,
                                                           Fn1<? super java.lang.Throwable,​? extends L> leftFn)
        Attempt to execute the Fn0, returning its result in a right value. If the supplier throws an exception, apply leftFn to it, wrap it in a left value and return it.
        Type Parameters:
        L - the left parameter type
        R - the right parameter type
        Parameters:
        fn0 - the supplier of the right value
        leftFn - a function mapping E to L
        Returns:
        the supplier result as a right value, or leftFn's mapping result as a left value
      • trying

        public static <R> Either<java.lang.Throwable,​R> trying​(Fn0<? extends R> fn0)
        Attempt to execute the Fn0, returning its result in a right value. If the supplier throws an exception, wrap it in a left value and return it.
        Type Parameters:
        R - the right parameter type
        Parameters:
        fn0 - the supplier of the right value
        Returns:
        the supplier result as a right value, or a left value of the thrown exception
      • trying

        public static <L> Either<L,​Unit> trying​(SideEffect sideEffect,
                                                      Fn1<? super java.lang.Throwable,​? extends L> leftFn)
        Attempt to execute the SideEffect, returning Unit in a right value. If the runnable throws an exception, apply leftFn to it, wrap it in a left value, and return it.
        Type Parameters:
        L - the left parameter type
        Parameters:
        sideEffect - the runnable
        leftFn - a function mapping E to L
        Returns:
        Unit as a right value, or leftFn's mapping result as a left value
      • trying

        public static Either<java.lang.Throwable,​Unit> trying​(SideEffect sideEffect)
        Attempt to execute the SideEffect, returning Unit in a right value. If the runnable throws exception, wrap it in a left value and return it.
        Parameters:
        sideEffect - the runnable
        Returns:
        Unit as a right value, or a left value of the thrown exception
      • left

        public static <L,​R> Either<L,​R> left​(L l)
        Static factory method for creating a left value.
        Type Parameters:
        L - the left parameter type
        R - the right parameter type
        Parameters:
        l - the wrapped value
        Returns:
        a left value of l
      • right

        public static <L,​R> Either<L,​R> right​(R r)
        Static factory method for creating a right value.
        Type Parameters:
        L - the left parameter type
        R - the right parameter type
        Parameters:
        r - the wrapped value
        Returns:
        a right value of r
      • pureEither

        public static <L> Pure<Either<L,​?>> pureEither()
        The canonical Pure instance for Either.
        Type Parameters:
        L - the left type
        Returns:
        the Pure instance