Package com.jnape.palatable.lambda.functor.builtin

Class State<S,A>

java.lang.Object

com.jnape.palatable.lambda.functor.builtin.State<S,A>

Type Parameters:

S - the state type

A - the result type

All Implemented Interfaces:

Applicative<A,State<S,?>>, Functor<A,State<S,?>>, Monad<A,State<S,?>>, MonadReader<S,A,State<S,?>>, MonadRec<A,State<S,?>>, MonadWriter<S,A,State<S,?>>

public final class State<S,A>
extends java.lang.Object
implements MonadRec<A,State<S,?>>, MonadReader<S,A,State<S,?>>, MonadWriter<S,A,State<S,?>>

The state Monad, useful for iteratively building up state and state-contextualized result.

For more information, read about the state monad.

Field Summary

Fields

Modifier and Type	Field	Description
private StateT<S,Identity<?>,A>	stateFn

Constructor Summary

Constructors

Modifier	Constructor	Description
private	State(StateT<S,Identity<?>,A> stateFn)

Method Summary

Modifier and Type	Method	Description
State<S,A>	censor(Fn1<? super S,? extends S> fn)	Update the accumulated state.
<B> State<S,B>	discardL(Applicative<B,State<S,?>> appB)	Sequence both this Applicative and appB, discarding this Applicative's result and returning appB.
<B> State<S,A>	discardR(Applicative<B,State<S,?>> appB)	Sequence both this Applicative and appB, discarding appB's result and returning this Applicative.
A	eval(S s)	Run the stateful computation, returning the result.
S	exec(S s)	Run the stateful computation, returning the final state.
<B> State<S,B>	flatMap(Fn1<? super A,? extends Monad<B,State<S,?>>> f)	Chain dependent computations that may continue or short-circuit based on previous results.
<B> State<S,B>	fmap(Fn1<? super A,? extends B> fn)	Covariantly transmute this functor's parameter using the given mapping function.
static <A> State<A,A>	get()	Create a State that simply returns back the initial state as both the result and the final state
static <S,A> State<S,A>	gets(Fn1<? super S,? extends A> fn)	Create a State that maps its initial state into its result, but leaves the initial state unchanged.
<B> Lazy<State<S,B>>	lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,State<S,?>>> 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> State<S,Tuple2<A,B>>	listens(Fn1<? super S,? extends B> fn)	Map the accumulation into a value and pair it with the current output.
State<S,A>	local(Fn1<? super S,? extends S> fn)	Modify this MonadReader's environment after reading it but before running the effect.
<B> State<S,B>	mapState(Fn1<? super Tuple2<A,S>,? extends Tuple2<B,S>> fn)	Map both the result and the final state to a new result and final state.
static <S> State<S,Unit>	modify(Fn1<? super S,? extends S> fn)	Create a State that maps its initial state into its final state, returning a Unit result type.
<B> State<S,B>	pure(B b)	Lift the value b into this applicative functor.
static <S> Pure<State<S,?>>	pureState()	The canonical Pure instance for State.
static <S> State<S,Unit>	put(S s)	Create a State that ignores its initial state, returning a Unit result and s as its final state.
Tuple2<A,S>	run(S s)	Run the stateful computation, returning a Tuple2 of the result and the final state.
static <S,A> State<S,A>	state(A a)	Create a State that returns a as its result and its initial state as its final state.
static <S,A> State<S,A>	state(Fn1<? super S,? extends Tuple2<A,S>> stateFn)	Create a State from stateFn, a function that maps an initial state into a result and a final state.
<B> State<S,B>	trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,State<S,?>>> fn)	Given some operation yielding a RecursiveResult inside this MonadRec, internally trampoline the operation until it yields a termination instruction.
State<S,A>	withState(Fn1<? super S,? extends S> fn)	Map the final state to a new final state using the provided function.
<B> State<S,B>	zip(Applicative<Fn1<? super A,? extends B>,State<S,?>> 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

Field Detail

stateFn

private final StateT<S,Identity<?>,A> stateFn

Constructor Detail

State

private State(StateT<S,Identity<?>,A> stateFn)

Method Detail

run

public Tuple2<A,S> run(S s)

Run the stateful computation, returning a Tuple2 of the result and the final state.

Parameters:

s - the initial state

Returns:

a Tuple2 of the result and the final state.

eval

public A eval(S s)

Run the stateful computation, returning the result.

Parameters:

s - the initial state

Returns:

the result

exec

public S exec(S s)

Run the stateful computation, returning the final state.

Parameters:

s - the initial state

Returns:

the final state

mapState

public <B> State<S,B> mapState(Fn1<? super Tuple2<A,S>,? extends Tuple2<B,S>> fn)

Map both the result and the final state to a new result and final state.

Type Parameters:

B - the new state type

Parameters:

fn - the mapping function

Returns:

the mapped State

withState

public State<S,A> withState(Fn1<? super S,? extends S> fn)

Map the final state to a new final state using the provided function.

Parameters:

fn - the state-mapping function

Returns:

the mapped State

local

public State<S,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,State<S,?>>

Parameters:

fn - the modification function

Returns:

the MonadReader with a modified environment

listens

public <B> State<S,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,State<S,?>>

Type Parameters:

B - the mapped output

Parameters:

fn - the mapping function

Returns:

the updated MonadWriter

censor

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

Update the accumulated state.

Specified by:

censor in interface MonadWriter<S,A,State<S,?>>

Parameters:

fn - the update function

Returns:

the updated MonadWriter

flatMap

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

Chain dependent computations that may continue or short-circuit based on previous results.

Specified by:

flatMap in interface Monad<S,A>

Specified by:

flatMap in interface MonadReader<S,A,State<S,?>>

Specified by:

flatMap in interface MonadRec<S,A>

Specified by:

flatMap in interface MonadWriter<S,A,State<S,?>>

Type Parameters:

B - the resulting monad parameter type

Parameters:

f - the dependent computation over A

Returns:

the new monad instance

pure

public <B> State<S,B> pure(B b)

Lift the value b into this applicative functor.

Specified by:

pure in interface Applicative<S,A>

Specified by:

pure in interface Monad<S,A>

Specified by:

pure in interface MonadReader<S,A,State<S,?>>

Specified by:

pure in interface MonadRec<S,A>

Specified by:

pure in interface MonadWriter<S,A,State<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> State<S,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<S,A>

Specified by:

fmap in interface Functor<S,A>

Specified by:

fmap in interface Monad<S,A>

Specified by:

fmap in interface MonadReader<S,A,State<S,?>>

Specified by:

fmap in interface MonadRec<S,A>

Specified by:

fmap in interface MonadWriter<S,A,State<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> State<S,B> zip(Applicative<Fn1<? super A,? extends B>,State<S,?>> 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,A>

Specified by:

zip in interface Monad<S,A>

Specified by:

zip in interface MonadReader<S,A,State<S,?>>

Specified by:

zip in interface MonadRec<S,A>

Specified by:

zip in interface MonadWriter<S,A,State<S,?>>

Type Parameters:

B - the resulting applicative parameter type

Parameters:

appFn - the other applicative instance

Returns:

the mapped applicative

lazyZip

public <B> Lazy<State<S,B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,State<S,?>>> 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,A>

Specified by:

lazyZip in interface Monad<S,A>

Specified by:

lazyZip in interface MonadReader<S,A,State<S,?>>

Specified by:

lazyZip in interface MonadRec<S,A>

Specified by:

lazyZip in interface MonadWriter<S,A,State<S,?>>

Type Parameters:

B - the resulting applicative parameter type

Parameters:

lazyAppFn - the lazy other applicative instance

Returns:

the mapped applicative

See Also:

Maybe, Either

discardR

public <B> State<S,A> discardR(Applicative<B,State<S,?>> 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,A>

Specified by:

discardR in interface Monad<S,A>

Specified by:

discardR in interface MonadReader<S,A,State<S,?>>

Specified by:

discardR in interface MonadRec<S,A>

Specified by:

discardR in interface MonadWriter<S,A,State<S,?>>

Type Parameters:

B - the type of appB's parameter

Parameters:

appB - the other Applicative

Returns:

this Applicative

discardL

public <B> State<S,B> discardL(Applicative<B,State<S,?>> 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,A>

Specified by:

discardL in interface Monad<S,A>

Specified by:

discardL in interface MonadReader<S,A,State<S,?>>

Specified by:

discardL in interface MonadRec<S,A>

Specified by:

discardL in interface MonadWriter<S,A,State<S,?>>

Type Parameters:

B - the type of the returned Applicative's parameter

Parameters:

appB - the other Applicative

Returns:

appB

trampolineM

public <B> State<S,B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,State<S,?>>> 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<S,A>

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 implementation, for an implementation leveraging an already stack-safe , for a implementation

get

public static <A> State<A,A> get()

Create a State that simply returns back the initial state as both the result and the final state

Type Parameters:

A - the state and result type

Returns:

the new State instance

put

public static <S> State<S,Unit> put(S s)

Create a State that ignores its initial state, returning a Unit result and s as its final state.

Type Parameters:

S - the state type

Parameters:

s - the final state

Returns:

the new State instance

gets

public static <S,A> State<S,A> gets(Fn1<? super S,? extends A> fn)

Create a State that maps its initial state into its result, but leaves the initial state unchanged.

Type Parameters:

S - the state type

A - the result type

Parameters:

fn - the mapping function

Returns:

the new State instance

modify

public static <S> State<S,Unit> modify(Fn1<? super S,? extends S> fn)

Create a State that maps its initial state into its final state, returning a Unit result type.

Type Parameters:

S - the state type

Parameters:

fn - the mapping function

Returns:

the new State instance

state

public static <S,A> State<S,A> state(A a)

Create a State that returns a as its result and its initial state as its final state.

Type Parameters:

S - the state type

A - the result type

Parameters:

a - the result

Returns:

the new State instance

state

public static <S,A> State<S,A> state(Fn1<? super S,? extends Tuple2<A,S>> stateFn)

Create a State from stateFn, a function that maps an initial state into a result and a final state.

Type Parameters:

S - the state type

A - the result type

Parameters:

stateFn - the state function

Returns:

the new State instance

pureState

public static <S> Pure<State<S,?>> pureState()

The canonical Pure instance for State.

Type Parameters:

S - the state type

Returns:

the Pure instance