com.jnape.palatable.lambda.monad.transformer.builtin

## Class EitherT<M extends MonadRec<?,M>,L,R>

- java.lang.Object
- - com.jnape.palatable.lambda.monad.transformer.builtin.EitherT<M,L,R>

- Type Parameters:
    `M` - the outer `stack-safe monad`
    `L` - the left type
    `R` - the right type
  All Implemented Interfaces:
    Applicative<R,EitherT<M,L,?>>, Bifunctor<L,R,EitherT<M,?,?>>, BoundedBifunctor<L,R,Object,Object,EitherT<M,?,?>>, Functor<R,EitherT<M,L,?>>, Monad<R,EitherT<M,L,?>>, MonadBase<M,R,EitherT<?,L,?>>, MonadRec<R,EitherT<M,L,?>>, MonadT<M,R,EitherT<M,L,?>,EitherT<?,L,?>>

      public final class EitherT<M extends MonadRec<?,M>,L,R>
      extends Object
      implements Bifunctor<L,R,EitherT<M,?,?>>, MonadT<M,R,EitherT<M,L,?>,EitherT<?,L,?>>

  A `monad transformer` for `Either`.

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `<L2,R2> EitherT<M,L2,R2>` | `biMap(Fn1<? super L,? extends L2> lFn, Fn1<? super R,? extends R2> rFn)` Dually map covariantly over both the left and right parameters.
    `<L2> EitherT<M,L2,R>` | `biMapL(Fn1<? super L,? extends L2> fn)` Covariantly map over the left parameter.
    `<R2> EitherT<M,L,R2>` | `biMapR(Fn1<? super R,? extends R2> fn)` Covariantly map over the right parameter.
    `<R2> EitherT<M,L,R2>` | `discardL(Applicative<R2,EitherT<M,L,?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<B> EitherT<M,L,R>` | `discardR(Applicative<B,EitherT<M,L,?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `static <M extends MonadRec<?,M>,L,R> EitherT<M,L,R>` | `eitherT(MonadRec<Either<L,R>,M> melr)` Static factory method for lifting a ``Monad`<`Either`<L, R>, M>` into an `EitherT`.
    `boolean` | `equals(Object other)`
    `<R2> EitherT<M,L,R2>` | `flatMap(Fn1<? super R,? extends Monad<R2,EitherT<M,L,?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<R2> EitherT<M,L,R2>` | `fmap(Fn1<? super R,? extends R2> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `int` | `hashCode()`
    `<R2> Lazy<EitherT<M,L,R2>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super R,? extends R2>,EitherT<M,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.
    `<R2,N extends MonadRec<?,N>> EitherT<N,L,R2>` | `lift(MonadRec<R2,N> mb)` Lift a new argument `MonadRec` into this `MonadBase`.
    `static <L> Lift<EitherT<?,L,?>>` | `liftEitherT()` `Lift` for `EitherT`.
    `<R2> EitherT<M,L,R2>` | `pure(R2 r2)` Lift the value `b` into this applicative functor.
    `static <M extends MonadRec<?,M>,L> Pure<EitherT<M,L,?>>` | `pureEitherT(Pure<M> pureM)` The canonical `Pure` instance for `EitherT`.
    `<MELR extends MonadRec<Either<L,R>,M>> MELR` | `runEitherT()` Recover the full structure of the embedded `Monad`.
    `String` | `toString()`
    `<R2> EitherT<M,L,R2>` | `trampolineM(Fn1<? super R,? extends MonadRec<RecursiveResult<R,R2>,EitherT<M,L,?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `<R2> EitherT<M,L,R2>` | `zip(Applicative<Fn1<? super R,? extends R2>,EitherT<M,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, finalize, getClass, notify, notifyAll, wait, wait, wait`

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

      `join`

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

      `coerce`

- - ### Method Detail

    - #### runEitherT

          public <MELR extends MonadRec<Either<L,R>,M>> MELR runEitherT()

      Recover the full structure of the embedded `Monad`.
      Type Parameters:
        `MELR` - the witnessed target type
      Returns:
        the embedded `Monad`

    - #### lift

          public <R2,N extends MonadRec<?,N>> EitherT<N,L,R2> lift(MonadRec<R2,N> mb)

      Lift a new argument `MonadRec` into this `MonadBase`.
      Specified by:
        `lift` in interface `MonadBase<M extends MonadRec<?,M>,R,EitherT<?,L,?>>`
      Specified by:
        `lift` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      Type Parameters:
        `R2` - the `MonadRec` carrier type
        `N` - the argument `MonadRec` witness
      Parameters:
        `mb` - the argument `MonadRec`
      Returns:
        the new `MonadBase`

    - #### flatMap

          public <R2> EitherT<M,L,R2> flatMap(Fn1<? super R,? extends Monad<R2,EitherT<M,L,?>>> f)

      Chain dependent computations that may continue or short-circuit based on previous results.
      Specified by:
        `flatMap` in interface `Monad<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `flatMap` in interface `MonadRec<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `flatMap` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      Type Parameters:
        `R2` - the resulting monad parameter type
      Parameters:
        `f` - the dependent computation over A
      Returns:
        the new monad instance

    - #### pure

          public <R2> EitherT<M,L,R2> pure(R2 r2)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `pure` in interface `Monad<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `pure` in interface `MonadRec<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `pure` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      Type Parameters:
        `R2` - the type of the returned applicative's parameter
      Parameters:
        `r2` - the value
      Returns:
        an instance of this applicative over b

    - #### fmap

          public <R2> EitherT<M,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<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `fmap` in interface `Functor<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `fmap` in interface `Monad<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `fmap` in interface `MonadRec<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `fmap` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      Type Parameters:
        `R2` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### zip

          public <R2> EitherT<M,L,R2> zip(Applicative<Fn1<? super R,? extends R2>,EitherT<M,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<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `zip` in interface `Monad<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `zip` in interface `MonadRec<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `zip` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      Type Parameters:
        `R2` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          public <R2> Lazy<EitherT<M,L,R2>> lazyZip(Lazy<? extends Applicative<Fn1<? super R,? extends R2>,EitherT<M,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<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `lazyZip` in interface `Monad<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `lazyZip` in interface `MonadRec<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `lazyZip` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      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 <R2> EitherT<M,L,R2> discardL(Applicative<R2,EitherT<M,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<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `discardL` in interface `Monad<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `discardL` in interface `MonadRec<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `discardL` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      Type Parameters:
        `R2` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          public <B> EitherT<M,L,R> discardR(Applicative<B,EitherT<M,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<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `discardR` in interface `Monad<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `discardR` in interface `MonadRec<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Specified by:
        `discardR` in interface `MonadT<M extends MonadRec<?,M>,R,EitherT<M extends MonadRec<?,M>,L,?>,EitherT<?,L,?>>`
      Type Parameters:
        `B` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### trampolineM

          public <R2> EitherT<M,L,R2> trampolineM(Fn1<? super R,? extends MonadRec<RecursiveResult<R,R2>,EitherT<M,L,?>>> 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<R,EitherT<M extends MonadRec<?,M>,L,?>>`
      Type Parameters:
        `R2` - 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`

    - #### biMap

          public <L2,R2> EitherT<M,L2,R2> biMap(Fn1<? super L,? extends L2> lFn,
                                                Fn1<? super R,? extends R2> rFn)

      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,EitherT<M extends MonadRec<?,M>,?,?>>`
      Specified by:
        `biMap` in interface `BoundedBifunctor<L,R,Object,Object,EitherT<M extends MonadRec<?,M>,?,?>>`
      Type Parameters:
        `L2` - the new left parameter type
        `R2` - the new right parameter type
      Parameters:
        `lFn` - the left parameter mapping function
        `rFn` - the right parameter mapping function
      Returns:
        a bifunctor over C (the new left parameter type) and D (the new right parameter type)

    - #### biMapL

          public <L2> EitherT<M,L2,R> biMapL(Fn1<? super L,? extends L2> fn)

      Covariantly map over the left parameter.
      Specified by:
        `biMapL` in interface `Bifunctor<L,R,EitherT<M extends MonadRec<?,M>,?,?>>`
      Specified by:
        `biMapL` in interface `BoundedBifunctor<L,R,Object,Object,EitherT<M extends MonadRec<?,M>,?,?>>`
      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 <R2> EitherT<M,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,EitherT<M extends MonadRec<?,M>,?,?>>`
      Specified by:
        `biMapR` in interface `BoundedBifunctor<L,R,Object,Object,EitherT<M extends MonadRec<?,M>,?,?>>`
      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)

    - #### equals

          public boolean equals(Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### eitherT

          public static <M extends MonadRec<?,M>,L,R> EitherT<M,L,R> eitherT(MonadRec<Either<L,R>,M> melr)

      Static factory method for lifting a ``Monad`<`Either`<L, R>, M>` into an `EitherT`.
      Type Parameters:
        `M` - the outer `Monad` unification parameter
        `L` - the left type
        `R` - the right type
      Parameters:
        `melr` - the `Monad`<`Either`<L, R>, M>
      Returns:
        the `EitherT`

    - #### pureEitherT

          public static <M extends MonadRec<?,M>,L> Pure<EitherT<M,L,?>> pureEitherT(Pure<M> pureM)

      The canonical `Pure` instance for `EitherT`.
      Type Parameters:
        `M` - the argument `Monad` witness
        `L` - the left type
      Parameters:
        `pureM` - the argument `Monad` `Pure`
      Returns:
        the `Pure` instance

    - #### liftEitherT

          public static <L> Lift<EitherT<?,L,?>> liftEitherT()

      `Lift` for `EitherT`.
      Type Parameters:
        `L` - the left type
      Returns:
        the `Monad`lifted into `EitherT`