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

## Class StateT<S,M extends MonadRec<?,M>,A>

- java.lang.Object
- - com.jnape.palatable.lambda.monad.transformer.builtin.StateT<S,M,A>

- Type Parameters:
    `S` - the state type
    `M` - the `monadic embedding`
    `A` - the result type
  All Implemented Interfaces:
    Applicative<A,StateT<S,M,?>>, Functor<A,StateT<S,M,?>>, Monad<A,StateT<S,M,?>>, MonadBase<M,A,StateT<S,?,?>>, MonadReader<S,A,StateT<S,M,?>>, MonadRec<A,StateT<S,M,?>>, MonadWriter<S,A,StateT<S,M,?>>, MonadT<M,A,StateT<S,M,?>,StateT<S,?,?>>

      public final class StateT<S,M extends MonadRec<?,M>,A>
      extends Object
      implements MonadT<M,A,StateT<S,M,?>,StateT<S,?,?>>, MonadReader<S,A,StateT<S,M,?>>, MonadWriter<S,A,StateT<S,M,?>>

  The `State` `monad transformer`.
  See Also:
    `State`

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `StateT<S,M,A>` | `censor(Fn1<? super S,? extends S> fn)` Update the accumulated state.
    `<B> StateT<S,M,B>` | `discardL(Applicative<B,StateT<S,M,?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<B> StateT<S,M,A>` | `discardR(Applicative<B,StateT<S,M,?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `<MA extends Monad<A,M>> MA` | `evalT(S s)` Run the stateful computation embedded in the `Monad`, returning the result.
    `<MS extends Monad<S,M>> MS` | `execT(S s)` Run the stateful computation embedded in the `Monad`, returning the final state.
    `<B> StateT<S,M,B>` | `flatMap(Fn1<? super A,? extends Monad<B,StateT<S,M,?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<B> StateT<S,M,B>` | `fmap(Fn1<? super A,? extends B> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `static <A,M extends MonadRec<?,M>> StateT<A,M,A>` | `get(Pure<M> pureM)` Given a `pure` construction of some `Monad`, produce a `StateT` that equates its output with its state.
    `static <S,M extends MonadRec<?,M>,A> StateT<S,M,A>` | `gets(Fn1<? super S,? extends MonadRec<A,M>> fn)` Given a function that produces a value inside a `monadic effect` from a state, produce a `StateT` that simply passes its state to the function and applies it.
    `<B> Lazy<StateT<S,M,B>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,StateT<S,M,?>>> 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.
    `<B,N extends MonadRec<?,N>> StateT<S,N,B>` | `lift(MonadRec<B,N> mb)` Lift a new argument `MonadRec` into this `MonadBase`.
    `static <S> Lift<StateT<S,?,?>>` | `liftStateT()` `Lift` for `StateT`.
    `<B> StateT<S,M,Tuple2<A,B>>` | `listens(Fn1<? super S,? extends B> fn)` Map the accumulation into a value and pair it with the current output.
    `StateT<S,M,A>` | `local(Fn1<? super S,? extends S> fn)` Modify this `MonadReader's` environment after reading it but before running the effect.
    `<N extends MonadRec<?,N>,B> StateT<S,N,B>` | `mapStateT(Fn1<? super MonadRec<Tuple2<A,S>,M>,? extends MonadRec<Tuple2<B,S>,N>> fn)` Map both the result and the final state to a new result and final state inside the `Monad`.
    `static <S,M extends MonadRec<?,M>> StateT<S,M,Unit>` | `modify(Fn1<? super S,? extends MonadRec<S,M>> updateFn)` Lift a function that makes a stateful modification inside an `Monad` into `StateT`.
    `<B> StateT<S,M,B>` | `pure(B b)` Lift the value `b` into this applicative functor.
    `static <S,M extends MonadRec<?,M>> Pure<StateT<S,M,?>>` | `pureStateT(Pure<M> pureM)` The canonical `Pure` instance for `StateT`.
    `static <S,M extends MonadRec<?,M>> StateT<S,M,Unit>` | `put(MonadRec<S,M> ms)` Lift a `monadic state` into `StateT`.
    `<MAS extends MonadRec<Tuple2<A,S>,M>> MAS` | `runStateT(S s)` Run the stateful computation embedded in the `Monad`, returning a `Tuple2` of the result and the final state.
    `static <S,M extends MonadRec<?,M>,A> StateT<S,M,A>` | `stateT(Fn1<? super S,? extends MonadRec<Tuple2<A,S>,M>> stateFn)` Lift a state-sensitive `monadically embedded` computation into `StateT`.
    `static <S,M extends MonadRec<?,M>,A> StateT<S,M,A>` | `stateT(MonadRec<A,M> ma)` Lift a `monadic value` into `StateT`.
    `<B> StateT<S,M,B>` | `trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,StateT<S,M,?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `StateT<S,M,A>` | `withStateT(Fn1<? super S,? extends MonadRec<S,M>> fn)` Map the final state to a new final state inside the same `monadic effect` using the provided function.
    `<B> StateT<S,M,B>` | `zip(Applicative<Fn1<? super A,? extends B>,StateT<S,M,?>> 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.monad.Monad

      `join`

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

      `coerce`

- - ### Method Detail

    - #### runStateT

          public <MAS extends MonadRec<Tuple2<A,S>,M>> MAS runStateT(S s)

      Run the stateful computation embedded in the `Monad`, returning a `Tuple2` of the result and the final state.
      Type Parameters:
        `MAS` - the inferred `Monad` result
      Parameters:
        `s` - the initial state
      Returns:
        a `Tuple2` of the result and the final state.

    - #### evalT

          public <MA extends Monad<A,M>> MA evalT(S s)

      Run the stateful computation embedded in the `Monad`, returning the result.
      Type Parameters:
        `MA` - the inferred `Monad` result
      Parameters:
        `s` - the initial state
      Returns:
        the result

    - #### execT

          public <MS extends Monad<S,M>> MS execT(S s)

      Run the stateful computation embedded in the `Monad`, returning the final state.
      Type Parameters:
        `MS` - the inferred `Monad` result
      Parameters:
        `s` - the initial state
      Returns:
        the final state

    - #### mapStateT

          public <N extends MonadRec<?,N>,B> StateT<S,N,B> mapStateT(Fn1<? super MonadRec<Tuple2<A,S>,M>,? extends MonadRec<Tuple2<B,S>,N>> fn)

      Map both the result and the final state to a new result and final state inside the `Monad`.
      Type Parameters:
        `N` - the new `monadic embedding` for this `StateT`
        `B` - the new state type
      Parameters:
        `fn` - the mapping function
      Returns:
        the mapped `StateT`

    - #### withStateT

          public StateT<S,M,A> withStateT(Fn1<? super S,? extends MonadRec<S,M>> fn)

      Map the final state to a new final state inside the same `monadic effect` using the provided function.
      Parameters:
        `fn` - the state-mapping function
      Returns:
        the mapped `StateT`

    - #### listens

          public <B> StateT<S,M,Tuple2<A,B>> listens(Fn1<? super S,? extends B> fn)

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

    - #### censor

          public StateT<S,M,A> censor(Fn1<? super S,? extends S> fn)

      Update the accumulated state.
      Specified by:
        `censor` in interface `MonadWriter<S,A,StateT<S,M extends MonadRec<?,M>,?>>`
      Parameters:
        `fn` - the update function
      Returns:
        the updated `MonadWriter`

    - #### local

          public StateT<S,M,A> local(Fn1<? super S,? extends S> fn)

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

    - #### flatMap

          public <B> StateT<S,M,B> flatMap(Fn1<? super A,? extends Monad<B,StateT<S,M,?>>> f)

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

    - #### pure

          public <B> StateT<S,M,B> pure(B b)

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

    - #### fmap

          public <B> StateT<S,M,B> fmap(Fn1<? super A,? extends B> 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<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `Functor<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `Monad<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `MonadReader<S,A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `MonadRec<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `MonadWriter<S,A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `fmap` in interface `MonadT<M extends MonadRec<?,M>,A,StateT<S,M extends MonadRec<?,M>,?>,StateT<S,?,?>>`
      Type Parameters:
        `B` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### zip

          public <B> StateT<S,M,B> zip(Applicative<Fn1<? super A,? extends B>,StateT<S,M,?>> 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<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `Monad<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `MonadReader<S,A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `MonadRec<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `MonadWriter<S,A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `zip` in interface `MonadT<M extends MonadRec<?,M>,A,StateT<S,M extends MonadRec<?,M>,?>,StateT<S,?,?>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

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

    - #### discardL

          public <B> StateT<S,M,B> discardL(Applicative<B,StateT<S,M,?>> 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<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `Monad<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `MonadReader<S,A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `MonadRec<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `MonadWriter<S,A,StateT<S,M extends MonadRec<?,M>,?>>`
      Specified by:
        `discardL` in interface `MonadT<M extends MonadRec<?,M>,A,StateT<S,M extends MonadRec<?,M>,?>,StateT<S,?,?>>`
      Type Parameters:
        `B` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

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

    - #### lift

          public <B,N extends MonadRec<?,N>> StateT<S,N,B> lift(MonadRec<B,N> mb)

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

    - #### trampolineM

          public <B> StateT<S,M,B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,StateT<S,M,?>>> 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<A,StateT<S,M extends MonadRec<?,M>,?>>`
      Type Parameters:
        `B` - 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`

    - #### get

          public static <A,M extends MonadRec<?,M>> StateT<A,M,A> get(Pure<M> pureM)

      Given a `pure` construction of some `Monad`, produce a `StateT` that equates its output with its state.
      Type Parameters:
        `A` - the state and value type
        `M` - the `Monad` embedding
      Parameters:
        `pureM` - the `pure` construction
      Returns:
        the `StateT`

    - #### gets

          public static <S,M extends MonadRec<?,M>,A> StateT<S,M,A> gets(Fn1<? super S,? extends MonadRec<A,M>> fn)

      Given a function that produces a value inside a `monadic effect` from a state, produce a `StateT` that simply passes its state to the function and applies it.
      Type Parameters:
        `S` - the state type
        `M` - the`Monad` embedding
        `A` - the value type
      Parameters:
        `fn` - the function
      Returns:
        the `StateT`

    - #### modify

          public static <S,M extends MonadRec<?,M>> StateT<S,M,Unit> modify(Fn1<? super S,? extends MonadRec<S,M>> updateFn)

      Lift a function that makes a stateful modification inside an `Monad` into `StateT`.
      Type Parameters:
        `S` - the state type
        `M` - the `Monad` embedding
      Parameters:
        `updateFn` - the update function
      Returns:
        the `StateT`

    - #### put

          public static <S,M extends MonadRec<?,M>> StateT<S,M,Unit> put(MonadRec<S,M> ms)

      Lift a `monadic state` into `StateT`.
      Type Parameters:
        `S` - the state type
        `M` - the `MonadRec` embedding
      Parameters:
        `ms` - the state
      Returns:
        the `StateT`

    - #### stateT

          public static <S,M extends MonadRec<?,M>,A> StateT<S,M,A> stateT(MonadRec<A,M> ma)

      Lift a `monadic value` into `StateT`.
      Type Parameters:
        `S` - the state type
        `M` - the `Monad` embedding
        `A` - the result type
      Parameters:
        `ma` - the value
      Returns:
        the `StateT`

    - #### stateT

          public static <S,M extends MonadRec<?,M>,A> StateT<S,M,A> stateT(Fn1<? super S,? extends MonadRec<Tuple2<A,S>,M>> stateFn)

      Lift a state-sensitive `monadically embedded` computation into `StateT`.
      Type Parameters:
        `S` - the state type
        `M` - the `Monad` embedding
        `A` - the result type
      Parameters:
        `stateFn` - the stateful operation
      Returns:
        the `StateT`

    - #### pureStateT

          public static <S,M extends MonadRec<?,M>> Pure<StateT<S,M,?>> pureStateT(Pure<M> pureM)

      The canonical `Pure` instance for `StateT`.
      Type Parameters:
        `S` - the state type
        `M` - the argument `Monad` witness
      Parameters:
        `pureM` - the argument `Monad` `Pure`
      Returns:
        the `Pure` instance

    - #### liftStateT

          public static <S> Lift<StateT<S,?,?>> liftStateT()

      `Lift` for `StateT`.
      Type Parameters:
        `S` - the state type
      Returns:
        the `Monad` lifted into `StateT`