Class IterateT<M extends MonadRec<?,M>,A>
- Type Parameters:
M
- the effect typeA
- the element type
- All Implemented Interfaces:
Applicative<A,
,IterateT<M, ?>> Functor<A,
,IterateT<M, ?>> Monad<A,
,IterateT<M, ?>> MonadBase<M,
,A, IterateT<?, ?>> MonadRec<A,
,IterateT<M, ?>> MonadT<M,
A, IterateT<M, ?>, IterateT<?, ?>>
monad transformer
over a co-inductive, singly-linked spine of values embedded in effects. This is
analogous to Haskell's ListT (done right). All append
operations (cons
, snoc
, etc.) are O(1) space/time
complexity.
Due to its singly-linked embedded design, IterateT
is a canonical example of purely-functional streaming
computation. For example, to lazily print all lines from a file descriptor, an initial implementation using
IterateT
might take the following form:
String filePath = "/tmp/a_tale_of_two_cities.txt";
IterateT<IO<?>, String> streamLines = IterateT.unfold(
reader -> io(() -> maybe(reader.readLine()).fmap(line -> tuple(line, reader))),
io(() -> Files.newBufferedReader(Paths.get(filePath))));
// iterative read and print lines without retaining references
IO<Unit> printLines = streamLines.forEach(line -> io(() -> System.out.println(line)));
printLines.unsafePerformIO(); // prints "It was the best of times, it was the worst of times, [...]"
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionAdd an element inside an effect to the front of thisIterateT
.discardL
(Applicative<B, IterateT<M, ?>> appB) Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
.discardR
(Applicative<B, IterateT<M, ?>> appB) Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
.Static factory method for creating an emptyIterateT
.Chain dependent computations that may continue or short-circuit based on previous results.Covariantly transmute this functor's parameter using the given mapping function.Monolithically fold the spine of thisIterateT
bytrampolining
the underlying effects (for iterative folding, usetrampolineM
directly).Monolithically fold the spine of thisIterateT
(with the possibility of early termination) bytrampolining
the underlying effects (for iterative folding, usetrampolineM
directly).fromIterator
(Iterator<A> as) Given alazy
instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.Static factory method for creating anIterateT
from a spine represented by one or more elements.pure
(B b) Lift the valueb
into this applicative functor.pureIterateT
(Pure<M> pureM) Recover the full structure of the embeddedMonad
.runStep()
Static factory method for creating anIterateT
from a single element.Add an element inside an effect to the back of thisIterateT
.<C extends Collection<A>,
MAS extends MonadRec<C, M>>
MAStoCollection
(Fn0<C> cFn0) Force the underlying spine of thisIterateT
into aCollection
of typeC
inside the context of the monadic effect, using the providedcFn0
to construct the initial instance.trampolineM
(Fn1<? super A, ? extends MonadRec<RecursiveResult<A, B>, IterateT<M, ?>>> fn) Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
instruction.Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
-
Field Details
-
pureM
-
spine
-
-
Constructor Details
-
IterateT
-
-
Method Details
-
runIterateT
Recover the full structure of the embeddedMonad
.- Type Parameters:
MMTA
- the witnessed target type- Returns:
- the embedded
Monad
-
runStep
Run a single step of thisIterateT
, where a step is the smallest amount of work that could possibly be productive in advancing through theIterateT
. Useful for implementing interleaving algorithms that requireIterateTs
to yield, emit, or terminate as soon as possible, regardless of whether the next element is readily available.- Type Parameters:
MStep
- the witnessed target type of the step- Returns:
- the step
-
cons
Add an element inside an effect to the front of thisIterateT
.- Parameters:
head
- the element- Returns:
- the cons'ed
IterateT
-
snoc
Add an element inside an effect to the back of thisIterateT
.- Parameters:
last
- the element- Returns:
- the snoc'ed
IterateT
-
concat
-
fold
public <B,MB extends MonadRec<B, MB foldM>> (Fn2<? super B, ? super A, ? extends MonadRec<B, M>> fn, MonadRec<B, M> acc) Monolithically fold the spine of thisIterateT
bytrampolining
the underlying effects (for iterative folding, usetrampolineM
directly).- Type Parameters:
B
- the accumulation typeMB
- the witnessed target result type- Parameters:
fn
- the folding functionacc
- the starting accumulation effect- Returns:
- the folded effect result
-
foldCut
public <B,MB extends MonadRec<B, MB foldCutM>> (Fn2<? super B, ? super A, ? extends MonadRec<RecursiveResult<B, B>, M>> fn, MonadRec<B, M> acc) Monolithically fold the spine of thisIterateT
(with the possibility of early termination) bytrampolining
the underlying effects (for iterative folding, usetrampolineM
directly).- Type Parameters:
B
- the accumulation typeMB
- the witnessed target result type- Parameters:
fn
- the folding functionacc
- the starting accumulation effect- Returns:
- the folded effect result
-
forEach
Convenience method forfolding
the spine of thisIterateT
with an action to perform on each element without accumulating any results.- Type Parameters:
MU
- the witnessed target result type- Parameters:
fn
- the action to perform on each element- Returns:
- the folded effect result
-
lift
- Specified by:
lift
in interfaceMonadBase<M extends MonadRec<?,
M>, A, IterateT<?, ?>> - Specified by:
lift
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- theMonadRec
carrier typeN
- the argumentMonadRec
witness- Parameters:
nb
- the argumentMonadRec
- Returns:
- the new
MonadBase
-
trampolineM
public <B> IterateT<M,B> trampolineM(Fn1<? super A, ? extends MonadRec<RecursiveResult<A, B>, IterateT<M, ?>>> fn) Given some operation yielding aRecursiveResult
inside thisMonadRec
, internally trampoline the operation until it yields atermination
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.
-
flatMap
Chain dependent computations that may continue or short-circuit based on previous results.- Specified by:
flatMap
in interfaceMonad<M extends MonadRec<?,
M>, A> - Specified by:
flatMap
in interfaceMonadRec<M extends MonadRec<?,
M>, A> - Specified by:
flatMap
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- the resulting monad parameter type- Parameters:
f
- the dependent computation over A- Returns:
- the new monad instance
-
fmap
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 interfaceApplicative<M extends MonadRec<?,
M>, A> - Specified by:
fmap
in interfaceFunctor<M extends MonadRec<?,
M>, A> - Specified by:
fmap
in interfaceMonad<M extends MonadRec<?,
M>, A> - Specified by:
fmap
in interfaceMonadRec<M extends MonadRec<?,
M>, A> - Specified by:
fmap
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- the new parameter type- Parameters:
fn
- the mapping function- Returns:
- a functor over B (the new parameter type)
-
pure
Lift the valueb
into this applicative functor.- Specified by:
pure
in interfaceApplicative<M extends MonadRec<?,
M>, A> - Specified by:
pure
in interfaceMonad<M extends MonadRec<?,
M>, A> - Specified by:
pure
in interfaceMonadRec<M extends MonadRec<?,
M>, A> - Specified by:
pure
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- the type of the returned applicative's parameter- Parameters:
b
- the value- Returns:
- an instance of this applicative over b
-
toCollection
Force the underlying spine of thisIterateT
into aCollection
of typeC
inside the context of the monadic effect, using the providedcFn0
to construct the initial instance.Note that this is a fundamentally monolithic operation - meaning that incremental progress is not possible - and as such, calling this on an infinite
IterateT
will result in either heap exhaustion (e.g. in the case oflists
) or non-termination (e.g. in the case ofsets
).- Type Parameters:
C
- theCollection
typeMAS
- the witnessed target type- Parameters:
cFn0
- theCollection
construction function- Returns:
- the
List
inside of the effect
-
zip
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 interfaceApplicative<M extends MonadRec<?,
M>, A> - Specified by:
zip
in interfaceMonad<M extends MonadRec<?,
M>, A> - Specified by:
zip
in interfaceMonadRec<M extends MonadRec<?,
M>, A> - Specified by:
zip
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- the resulting applicative parameter type- Parameters:
appFn
- the other applicative instance- Returns:
- the mapped applicative
-
lazyZip
public <B> Lazy<IterateT<M,B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A, ? extends B>, IterateT<M, ?>>> lazyAppFn) Given alazy
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 interfaceApplicative<M extends MonadRec<?,
M>, A> - Specified by:
lazyZip
in interfaceMonad<M extends MonadRec<?,
M>, A> - Specified by:
lazyZip
in interfaceMonadRec<M extends MonadRec<?,
M>, A> - Specified by:
lazyZip
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- the resulting applicative parameter type- Parameters:
lazyAppFn
- the lazy other applicative instance- Returns:
- the mapped applicative
- See Also:
-
discardL
Sequence both thisApplicative
andappB
, discarding thisApplicative's
result and returningappB
. This is generally useful for sequentially performing side-effects.- Specified by:
discardL
in interfaceApplicative<M extends MonadRec<?,
M>, A> - Specified by:
discardL
in interfaceMonad<M extends MonadRec<?,
M>, A> - Specified by:
discardL
in interfaceMonadRec<M extends MonadRec<?,
M>, A> - Specified by:
discardL
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- the type of the returned Applicative's parameter- Parameters:
appB
- the other Applicative- Returns:
- appB
-
discardR
Sequence both thisApplicative
andappB
, discardingappB's
result and returning thisApplicative
. This is generally useful for sequentially performing side-effects.- Specified by:
discardR
in interfaceApplicative<M extends MonadRec<?,
M>, A> - Specified by:
discardR
in interfaceMonad<M extends MonadRec<?,
M>, A> - Specified by:
discardR
in interfaceMonadRec<M extends MonadRec<?,
M>, A> - Specified by:
discardR
in interfaceMonadT<M extends MonadRec<?,
M>, A, IterateT<M extends MonadRec<?, M>, ?>, IterateT<?, ?>> - Type Parameters:
B
- the type of appB's parameter- Parameters:
appB
- the other Applicative- Returns:
- this Applicative
-
empty
Static factory method for creating an emptyIterateT
. -
singleton
Static factory method for creating anIterateT
from a single element.- Type Parameters:
M
- the effect typeA
- the element type- Parameters:
ma
- the element- Returns:
- the singleton
IterateT
-
iterateT
public static <M extends MonadRec<?,M>, IterateT<M,A> A> iterateT(MonadRec<Maybe<Tuple2<A, IterateT<M, A>>>, M> unwrapped) - Type Parameters:
M
- the effect typeA
- the element type- Parameters:
unwrapped
- the uncons- Returns:
- the wrapped
IterateT
-
of
@SafeVarargs public static <M extends MonadRec<?,M>, IterateT<M,A> A> of(MonadRec<A, M> ma, MonadRec<A, M>... mas) Static factory method for creating anIterateT
from a spine represented by one or more elements.- Type Parameters:
M
- the effect typeA
- the element type- Parameters:
ma
- the head elementmas
- the tail elements- Returns:
- the
IterateT
-
unfold
public static <M extends MonadRec<?,M>, IterateT<M,A, B> A> unfold(Fn1<? super B, ? extends MonadRec<Maybe<Tuple2<A, B>>, M>> fn, MonadRec<B, M> mb) Lazily unfold anIterateT
from an unfolding functionfn
and a starting seed valuemb
by successively applyingfn
to the latest seed value, producingmaybe
a value to yield out and the next seed value for the subsequent computation.- Type Parameters:
M
- the effect typeA
- the element typeB
- the seed type- Parameters:
fn
- the unfolding functionmb
- the starting seed value- Returns:
- the lazily unfolding
IterateT
-
suspended
public static <M extends MonadRec<?,M>, IterateT<M,A> A> suspended(Fn0<MonadRec<Maybe<Tuple2<A, IterateT<M, A>>>, M>> thunk, Pure<M> pureM) -
fromIterator
-
pureIterateT
-
liftIterateT
-