A stream is a succession of Steps. A Yield produces a single value and the next state of the stream. Stop indicates there are no more values in the stream.

An Unfold m a b is a generator of a stream of values of type b from a seed of type a in Monad m.

Make an unfold from step and inject functions.

Pre-release

Make an unfold from a step function.

See also: unfoldrM

Pre-release

Build a stream by unfolding a monadic step function starting from a seed. The step function returns the next element in the stream and the next seed value. When it is done it returns Nothing and the stream ends.

Like unfoldrM but uses a pure step function.

>>> :{
 f [] = Nothing
 f (x:xs) = Just (x, xs)
:}

>>> Unfold.fold Fold.toList (Unfold.unfoldr f) [1,2,3]
[1,2,3]

Lift a monadic function into an unfold. The unfold generates a singleton stream.

Lift a pure function into an unfold. The unfold generates a singleton stream.

function f = functionM $ return . f

Identity unfold. The unfold generates a singleton stream having the input as the only element.

identity = function Prelude.id

Pre-release

The unfold discards its input and generates a function stream using the supplied monadic action.

Pre-release

Discards the unfold input and always returns the argument of fromPure.

fromPure = fromEffect . pure

Pre-release

Convert a list of pure values to a Stream

Map a function on the input argument of the Unfold.

>>> u = Unfold.lmap (fmap (+1)) Unfold.fromList
>>> Unfold.fold Fold.toList u [1..5]
[2,3,4,5,6]

lmap f = Unfold.many (Unfold.function f)

Map an action on the input argument of the Unfold.

lmapM f = Unfold.many (Unfold.functionM f)

Map a function on the output of the unfold (the type b).

>>> map f = Unfold.map2 (const f)

Pre-release

>>> map2 f = Unfold.mapM2 (\a b -> pure (f a b))

Note that the seed may mutate (e.g. if the seed is a Handle or IORef) as stream is generated from it, so we need to be careful when reusing the seed while the stream is being generated from it.

Apply a monadic function to each element of the stream and replace it with the output of the resulting action.

>>> mapM f = Unfold.mapM2 (const f)

Supply the seed to an unfold closing the input end of the unfold.

both a = Unfold.lmap (Prelude.const a)

Pre-release

Supply the first component of the tuple to an unfold that accepts a tuple as a seed resulting in a fold that accepts the second component of the tuple as a seed.

first a = Unfold.lmap (a, )

Pre-release

Supply the second component of the tuple to an unfold that accepts a tuple as a seed resulting in a fold that accepts the first component of the tuple as a seed.

second b = Unfold.lmap (, b)

Pre-release

Same as takeWhile but with a monadic predicate.

End the stream generated by the Unfold as soon as the predicate fails on an element.

Apply the first unfold to each output element of the second unfold and flatten the output in a single stream.

>>> many u = Unfold.many2 (Unfold.lmap snd u)

unfoldManyInterleave for documentation and notes.

This is almost identical to unfoldManyInterleave in StreamD module.

The many combinator is in fact manyAppend to be more explicit in naming.

Internal

Outer product discarding the first element.

Unimplemented

Outer product discarding the second element.

Unimplemented

Create a cross product (vector product or cartesian product) of the output streams of two unfolds using a monadic combining function.

>>> f1 f u = Unfold.mapM2 (\(_, c) b -> f b c) (Unfold.lmap fst u)
>>> crossWithM f u = Unfold.many2 (f1 f u)

Pre-release

Like crossWithM but uses a pure combining function.

crossWith f = crossWithM (\b c -> return $ f b c)

>>> u1 = Unfold.lmap fst Unfold.fromList
>>> u2 = Unfold.lmap snd Unfold.fromList
>>> u = Unfold.crossWith (,) u1 u2
>>> Unfold.fold Fold.toList u ([1,2,3], [4,5,6])
[(1,4),(1,5),(1,6),(2,4),(2,5),(2,6),(3,4),(3,5),(3,6)]

See crossWith.

Definition:

>>> cross = Unfold.crossWith (,)

To create a cross product of the streams generated from a tuple we can write:

>>> :{
cross :: Monad m => Unfold m a b -> Unfold m c d -> Unfold m (a, c) (b, d)
cross u1 u2 = Unfold.cross (Unfold.lmap fst u1) (Unfold.lmap snd u2)
:}

Pre-release

Map an unfold generating action to each element of an unfold and flatten the results into a single stream.

Distribute the input to two unfolds and then zip the outputs to a single stream using a monadic zip function.

Stops as soon as any of the unfolds stops.

Pre-release

Like zipWithM but with a pure zip function.

>>> square = fmap (\x -> x * x) Unfold.fromList
>>> cube = fmap (\x -> x * x * x) Unfold.fromList
>>> u = Unfold.zipWith (,) square cube
>>> Unfold.fold Fold.toList u [1..5]
[(1,1),(4,8),(9,27),(16,64),(25,125)]

zipWith f = zipWithM (\a b -> return $ f a b)

Lift a monadic function into an unfold generating a nil stream with a side effect.

An empty stream.

Prepend a monadic single element generator function to an Unfold. The same seed is used in the action as well as the unfold.

Pre-release

Generates an infinite stream repeating the seed.

Given a seed (n, action), generates a stream replicating the action n times.

fromIndicesM gen generates an infinite stream of values using gen starting from the seed.

fromIndicesM f = Unfold.mapM f $ Unfold.enumerateFrom 0

Pre-release

Generates an infinite stream starting with the given seed and applying the given function repeatedly.

Types that can be enumerated as a stream. The operations in this type class are equivalent to those in the Enum type class, except that these generate a stream instead of a list. Use the functions in Streamly.Internal.Data.Unfold.Enumeration module to define new instances.

Pre-release

Unfolds (from, stride) generating an infinite stream starting from from and incrementing every time by stride. For Bounded types, after the value overflows it keeps enumerating in a cycle:

>>> Stream.toList $ Stream.take 10 $ Stream.unfold Unfold.enumerateFromStepNum (255::Word8,1)
[255,0,1,2,3,4,5,6,7,8]

The implementation is numerically stable for floating point values.

Note enumerateFromStepIntegral is faster for integrals.

Internal

Same as enumerateFromStepNum using a stride of 1:

>>> enumerateFromNum = lmap (from -> (from, 1)) Unfold.enumerateFromStepNum
>>> Stream.toList $ Stream.take 6 $ Stream.unfold enumerateFromNum (0.9)
[0.9,1.9,2.9,3.9,4.9,5.9]

Also, same as enumerateFromThenNum using a stride of 1 but see the note in enumerateFromThenNum about the loss of precision:

>>> enumerateFromNum = lmap (from -> (from, from + 1)) Unfold.enumerateFromThenNum
>>> Stream.toList $ Stream.take 6 $ Stream.unfold enumerateFromNum (0.9)
[0.9,1.9,2.9,3.8999999999999995,4.8999999999999995,5.8999999999999995]

Internal

Same as 'enumerateFromStepNum (from, next)' using a stride of next - from:

>>> enumerateFromThenNum = lmap ((from, next) -> (from, next - from)) Unfold.enumerateFromStepNum

Example: @ >>> Stream.toList $ Stream.take 10 $ Stream.unfold enumerateFromThenNum (255::Word8,0) [255,0,1,2,3,4,5,6,7,8]

The implementation is numerically stable for floating point values.

Note that enumerateFromThenIntegral is faster for integrals.

Note that in the strange world of floating point numbers, using

enumerateFromThenNum (from, from + 1) is almost exactly the same as enumerateFromStepNum (from, 1) but not precisely the same. Because (from + 1) - from is not exactly 1, it may lose some precision, the loss may also be aggregated in each step, if you want that precision then use enumerateFromStepNum instead.

Internal

Can be used to enumerate unbounded integrals. This does not check for overflow or underflow for bounded integrals.

Internal

Enumerate from given starting Enum value from with stride of 1 till maxBound

Internal

Enumerate from given starting Enum value from and next Enum value next with stride of (fromEnum next - fromEnum from) till maxBound.

Internal

Enumerate from given starting Enum value from and to Enum value to with stride of 1 till to value.

Internal

Enumerate from given starting Enum value from and then Enum value next and to Enum value to with stride of (fromEnum next - fromEnum from) till to value.

Internal

Same as enumerateFromStepNum with a step of 1 and enumerating up to the specified upper limit rounded to the nearest integral value:

>>> Stream.toList $ Stream.unfold Unfold.enumerateFromToFractional (0.1, 6.3)
[0.1,1.1,2.1,3.1,4.1,5.1,6.1]

Internal

Convert a list of monadic values to a Stream

Convert an Unfold into an unfold accepting a tuple as an argument, using the argument of the original fold as the second element of tuple and discarding the first element of the tuple.

discardFirst = Unfold.lmap snd

Pre-release

Convert an Unfold into an unfold accepting a tuple as an argument, using the argument of the original fold as the first element of tuple and discarding the second element of the tuple.

discardSecond = Unfold.lmap fst

Pre-release

Convert an Unfold that accepts a tuple as an argument into an unfold that accepts a tuple with elements swapped.

swap = Unfold.lmap Tuple.swap

Pre-release

Compose an Unfold and a Fold. Given an Unfold m a b and a Fold m b c, returns a monadic action a -> m c representing the application of the fold on the unfolded stream.

>>> Unfold.fold Fold.sum Unfold.fromList [1..100]
5050

>>> fold f u = Stream.fold f . Stream.unfold u

Pre-release

Scan the output of an Unfold to change it in a stateful manner.

Pre-release

Scan the output of an Unfold to change it in a stateful manner.

Pre-release

Scan the output of an Unfold to change it in a stateful manner. Once fold is done it will stop.

>>> u = Unfold.scan (Fold.take 2 Fold.sum) Unfold.fromList
>>> Unfold.fold Fold.toList u [1,2,3,4,5]
[0,1,3]

Pre-release

Scan the output of an Unfold to change it in a stateful manner. Once fold is done it will restart from its initial state.

>>> u = Unfold.scanMany (Fold.take 2 Fold.sum) Unfold.fromList
>>> Unfold.fold Fold.toList u [1,2,3,4,5]
[0,1,3,0,3,7,0,5]

Pre-release

Apply a fold multiple times on the output of an unfold.

Pre-release

Choose left or right unfold based on an either input.

Pre-release

>>> u = Unfold.take 2 Unfold.fromList
>>> Unfold.fold Fold.toList u [1..100]
[1,2]

Include only those elements that pass a predicate.

Same as filter but with a monadic predicate.

drop n unf drops n elements from the stream generated by unf.

Similar to dropWhileM but with a pure condition function.

dropWhileM f unf drops elements from the stream generated by unf while the condition holds true. The condition function f is monadic in nature.

Like gbracketIO but with following differences:

• alloc action a -> m c runs with async exceptions enabled
• cleanup action c -> m d won't run if the stream is garbage collected after partial evaluation.

Inhibits stream fusion

Pre-release

Run the alloc action a -> m c with async exceptions disabled but keeping blocking operations interruptible (see mask). Use the output c as input to Unfold m c b to generate an output stream. When unfolding use the supplied try operation forall s. m s -> m (Either e s) to catch synchronous exceptions. If an exception occurs run the exception handling unfold Unfold m (c, e) b.

The cleanup action c -> m d, runs whenever the stream ends normally, due to a sync or async exception or if it gets garbage collected after a partial lazy evaluation. See bracket for the semantics of the cleanup action.

gbracket can express all other exception handling combinators.

Inhibits stream fusion

Pre-release

Run a side effect a -> m c on the input a before unfolding it using Unfold m a b.

before f = lmapM (\a -> f a >> return a)

Pre-release

Unfold the input a using Unfold m a b, run an action on a whenever the unfold stops normally, or if it is garbage collected after a partial lazy evaluation.

The semantics of the action a -> m c are similar to the cleanup action semantics in bracket.

See also after_

Pre-release

Like after with following differences:

• action a -> m c won't run if the stream is garbage collected after partial evaluation.
• Monad m does not require any other constraints.

Pre-release

Unfold the input a using Unfold m a b, run an action on a whenever the unfold stops normally, aborts due to an exception or if it is garbage collected after a partial lazy evaluation.

The semantics of the action a -> m c are similar to the cleanup action semantics in bracket.

finally release = bracket return release

See also finally_

Inhibits stream fusion

Pre-release

Like finallyIO with following differences:

• action a -> m c won't run if the stream is garbage collected after partial evaluation.

Inhibits stream fusion

Pre-release

Run the alloc action a -> m c with async exceptions disabled but keeping blocking operations interruptible (see mask). Use the output c as input to Unfold m c b to generate an output stream.

c is usually a resource under the state of monad m, e.g. a file handle, that requires a cleanup after use. The cleanup action c -> m d, runs whenever the stream ends normally, due to a sync or async exception or if it gets garbage collected after a partial lazy evaluation.

bracket only guarantees that the cleanup action runs, and it runs with async exceptions enabled. The action must ensure that it can successfully cleanup the resource in the face of sync or async exceptions.

When the stream ends normally or on a sync exception, cleanup action runs immediately in the current thread context, whereas in other cases it runs in the GC context, therefore, cleanup may be delayed until the GC gets to run.

See also: bracket_, gbracket

Inhibits stream fusion

Pre-release

Like bracketIO but with following differences:

• alloc action a -> m c runs with async exceptions enabled
• cleanup action c -> m d won't run if the stream is garbage collected after partial evaluation.

Inhibits stream fusion

Pre-release

Unfold the input a using Unfold m a b, run the action a -> m c on a if the unfold aborts due to an exception.

Inhibits stream fusion

Pre-release

When unfolding Unfold m a b if an exception e occurs, unfold e using Unfold m e b.

Inhibits stream fusion

Pre-release