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

Class IterateT<M extends MonadRec<?,​M>,​A>

  • Type Parameters:
    M - the effect type
    A - 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<?,​?>>
    public class IterateT<M extends MonadRec<?,​M>,​A>
extends java.lang.Object
implements MonadT<M,​A,​IterateT<M,​?>,​IterateT<?,​?>>
    A 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, [...]"

    • Method Detail

      • runIterateT

        public <MMTA extends MonadRec<Maybe<Tuple2<A,​IterateT<M,​A>>>,​M>> MMTA runIterateT()
        Recover the full structure of the embedded Monad.
        Type Parameters:
        MMTA - the witnessed target type
        Returns:
        the embedded Monad

      • runStep

        public <MStep extends MonadRec<Maybe<Tuple2<Maybe<A>,​IterateT<M,​A>>>,​M>> MStep runStep()
        Run a single step of this IterateT, where a step is the smallest amount of work that could possibly be productive in advancing through the IterateT. Useful for implementing interleaving algorithms that require IterateTs 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

        public final IterateT<M,​A> cons​(MonadRec<A,​M> head)
        Add an element inside an effect to the front of this IterateT.
        Parameters:
        head - the element
        Returns:
        the cons'ed IterateT

      • snoc

        public final IterateT<M,​A> snoc​(MonadRec<A,​M> last)
        Add an element inside an effect to the back of this IterateT.
        Parameters:
        last - the element
        Returns:
        the snoc'ed IterateT

      • fold

        public <B,​MB extends MonadRec<B,​M>> MB fold​(Fn2<? super B,​? super A,​? extends MonadRec<B,​M>> fn,
                                                        MonadRec<B,​M> acc)
        Monolithically fold the spine of this IterateT by trampolining the underlying effects (for iterative folding, use trampolineM directly).
        Type Parameters:
        B - the accumulation type
        MB - the witnessed target result type
        Parameters:
        fn - the folding function
        acc - the starting accumulation effect
        Returns:
        the folded effect result

      • foldCut

        public <B,​MB extends MonadRec<B,​M>> MB foldCut​(Fn2<? super B,​? super A,​? extends MonadRec<RecursiveResult<B,​B>,​M>> fn,
                                                           MonadRec<B,​M> acc)
        Monolithically fold the spine of this IterateT (with the possibility of early termination) by trampolining the underlying effects (for iterative folding, use trampolineM directly).
        Type Parameters:
        B - the accumulation type
        MB - the witnessed target result type
        Parameters:
        fn - the folding function
        acc - the starting accumulation effect
        Returns:
        the folded effect result

      • forEach

        public <MU extends MonadRec<Unit,​M>> MU forEach​(Fn1<? super A,​? extends MonadRec<Unit,​M>> fn)
        Convenience method for folding the spine of this IterateT 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

      • flatMap

        public <B> IterateT<M,​B> flatMap​(Fn1<? super A,​? extends Monad<B,​IterateT<M,​?>>> f)
        Chain dependent computations that may continue or short-circuit based on previous results.
        Specified by:
        flatMap in interface Monad<M extends MonadRec<?,​M>,​A>
        Specified by:
        flatMap in interface MonadRec<M extends MonadRec<?,​M>,​A>
        Specified by:
        flatMap in interface MonadT<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

        public <B> IterateT<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<M extends MonadRec<?,​M>,​A>
        Specified by:
        fmap in interface Functor<M extends MonadRec<?,​M>,​A>
        Specified by:
        fmap in interface Monad<M extends MonadRec<?,​M>,​A>
        Specified by:
        fmap in interface MonadRec<M extends MonadRec<?,​M>,​A>
        Specified by:
        fmap in interface MonadT<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)

      • toCollection

        public <C extends java.util.Collection<A>,​MAS extends MonadRec<C,​M>> MAS toCollection​(Fn0<C> cFn0)
        Force the underlying spine of this IterateT into a Collection of type C inside the context of the monadic effect, using the provided cFn0 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 of lists) or non-termination (e.g. in the case of sets).

        Type Parameters:
        C - the Collection type
        MAS - the witnessed target type
        Parameters:
        cFn0 - the Collection construction function
        Returns:
        the List inside of the effect

      • zip

        public <B> IterateT<M,​B> zip​(Applicative<Fn1<? super A,​? extends B>,​IterateT<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<M extends MonadRec<?,​M>,​A>
        Specified by:
        zip in interface Monad<M extends MonadRec<?,​M>,​A>
        Specified by:
        zip in interface MonadRec<M extends MonadRec<?,​M>,​A>
        Specified by:
        zip in interface MonadT<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 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<M extends MonadRec<?,​M>,​A>
        Specified by:
        lazyZip in interface Monad<M extends MonadRec<?,​M>,​A>
        Specified by:
        lazyZip in interface MonadRec<M extends MonadRec<?,​M>,​A>
        Specified by:
        lazyZip in interface MonadT<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:
        Maybe, Either

      • empty

        public static <M extends MonadRec<?,​M>,​A> IterateT<M,​A> empty​(Pure<M> pureM)
        Static factory method for creating an empty IterateT.
        Type Parameters:
        M - the effect type
        A - the element type
        Parameters:
        pureM - the Pure method for the effect
        Returns:
        the empty IterateT

      • singleton

        public static <M extends MonadRec<?,​M>,​A> IterateT<M,​A> singleton​(MonadRec<A,​M> ma)
        Static factory method for creating an IterateT from a single element.
        Type Parameters:
        M - the effect type
        A - the element type
        Parameters:
        ma - the element
        Returns:
        the singleton IterateT

      • iterateT

        public static <M extends MonadRec<?,​M>,​A> IterateT<M,​A> iterateT​(MonadRec<Maybe<Tuple2<A,​IterateT<M,​A>>>,​M> unwrapped)
        Static factory method for wrapping an uncons of an IterateT in an IterateT.
        Type Parameters:
        M - the effect type
        A - the element type
        Parameters:
        unwrapped - the uncons
        Returns:
        the wrapped IterateT

      • of

        @SafeVarargs
public static <M extends MonadRec<?,​M>,​A> IterateT<M,​A> of​(MonadRec<A,​M> ma,
                                                                             MonadRec<A,​M>... mas)
        Static factory method for creating an IterateT from a spine represented by one or more elements.
        Type Parameters:
        M - the effect type
        A - the element type
        Parameters:
        ma - the head element
        mas - the tail elements
        Returns:
        the IterateT

      • unfold

        public static <M extends MonadRec<?,​M>,​A,​B> IterateT<M,​A> unfold​(Fn1<? super B,​? extends MonadRec<Maybe<Tuple2<A,​B>>,​M>> fn,
                                                                                         MonadRec<B,​M> mb)
        Lazily unfold an IterateT from an unfolding function fn and a starting seed value mb by successively applying fn to the latest seed value, producing maybe a value to yield out and the next seed value for the subsequent computation.
        Type Parameters:
        M - the effect type
        A - the element type
        B - the seed type
        Parameters:
        fn - the unfolding function
        mb - the starting seed value
        Returns:
        the lazily unfolding IterateT

      • suspended

        public static <M extends MonadRec<?,​M>,​A> IterateT<M,​A> suspended​(Fn0<MonadRec<Maybe<Tuple2<A,​IterateT<M,​A>>>,​M>> thunk,
                                                                                    Pure<M> pureM)
        Create an IterateT from a suspended computation that yields the spine of the IterateT inside the effect.
        Type Parameters:
        M - the effect type
        A - the element type
        Parameters:
        thunk - the suspended computation
        pureM - the Pure method for the effect
        Returns:
        the IterateT

      • fromIterator

        public static <A> IterateT<IO<?>,​A> fromIterator​(java.util.Iterator<A> as)
        Lazily unfold an IterateT from an Iterator inside IO.
        Type Parameters:
        A - the element type
        Parameters:
        as - the Iterator
        Returns:
        the IterateT

      • pureIterateT

        public static <M extends MonadRec<?,​M>> Pure<IterateT<M,​?>> pureIterateT​(Pure<M> pureM)
        The canonical Pure instance for IterateT.
        Type Parameters:
        M - the argument Monad witness
        Parameters:
        pureM - the argument Monad Pure
        Returns:
        the Pure instance