Streamly.Internal.Data.Unfold

Setup

To execute the code examples provided in this module in ghci, please run the following commands first.

>>> :m
>>> import Streamly.Data.Unfold (Unfold)
>>> import qualified Streamly.Data.Fold as Fold
>>> import qualified Streamly.Data.Stream as Stream
>>> import qualified Streamly.Data.Unfold as Unfold

For APIs that have not been released yet.

>>> import qualified Streamly.Internal.Data.Unfold as Unfold

Unfold Type

General Notes

What makes streams less efficient is also what makes them more convenient to use and powerful. The stream data type (Stream m a) bundles the state along with the stream generator function making it opaque, whereas an unfold exposes the state (Unfold m s a) to the user. This allows the Unfold to be unfolded (inlined) inside a nested loop without having to bundle the state and the generator together, the stream state can be saved and passed independent of the generator function. On the other hand in a stream type we have to bundle the stream state and the generator function together to save the stream. This makes it inefficient because it requires boxing and constructor allocation. However, this makes streams more convenient as we do not need to pass around the state/seed separately.

Unfold Type:

The order of arguments allows Category and Arrow instances but precludes contravariant and contra-applicative.

Unfolds and Streams

An Unfold type is the same as the direct style Stream type except that it uses an inject function to determine the initial state of the stream based on an input. A stream is a special case of Unfold when the static input is unit or Void.

This allows an important optimization to occur in several cases, making the Unfold a more efficient abstraction. Consider the concatMap and unfoldMany operations, the latter is more efficient. concatMap generates a new stream object from each element in the stream by applying the supplied function to the element, the stream object includes the "step" function as well as the initial "state" of the stream. Since the stream is generated dynamically the compiler does not know the step function or the state type statically at compile time, therefore, it cannot inline it. On the other hand in case of unfoldMany the compiler has visibility into the unfold's state generation function, therefore, the compiler knows all the types statically and it can inline the inject as well as the step functions, generating efficient code. Essentially, the stream is not opaque to the consumer in case of unfolds, the consumer knows how to generate the stream from a seed using a known "inject" and "step" functions.

A Stream is like a data object whereas unfold is like a function. Being function like, an Unfold is an instance of Category and Arrow type classes.

Unfolds and Folds

Streams forcing a closed control flow loop can be categorized under two types, unfolds and folds, both of these are duals of each other.

Unfold streams are really generators of a sequence of elements, we can also call them pull style streams. These are lazy producers of streams. On each evaluation the producer generates the next element. A consumer can therefore pull elements from the stream whenever it wants to. A stream consumer can multiplex pull streams by pulling elements from the chosen streams, therefore, pull streams allow merging or multiplexing. On the other hand, with this representation we cannot split or demultiplex a stream. So really these are stream sources that can be generated from a seed and can be merged or zipped into a single stream.

The dual of Unfolds are Folds. Folds can also be called as push style streams or reducers. These are strict consumers of streams. We keep pushing elements to a fold and we can extract the result at any point. A driver can choose which fold to push to and can also push the same element to multiple folds. Therefore, folds allow splitting or demultiplexing a stream. On the other hand, we cannot merge streams using this representation. So really these are stream consumers that reduce the stream to a single value, these consumers can be composed such that a stream can be split over multiple consumers.

Performance:

Composing a tree or graph of computations with unfolds can be much more efficient compared to composing with the Monad instance. The reason is that unfolds allow the compiler to statically know the state and optimize it using stream fusion whereas it is not possible with the monad bind because the state is determined dynamically.

Reader:

An unfold acts as a reader (see Reader monad). The input to an unfold acts as the read-only environment. The environment can be extracted using the identity unfold (equivalent to ask) and transformed using lmap.

Type

data Step s a

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.

Constructors

Yield a s

Skip s

Stop

Instances

Functor (Step s)

Defined in Streamly.Internal.Data.Stream.Step

Methods

fmap :: (a -> b) -> Step s a -> Step s b

(<$) :: a -> Step s b -> Step s a

data Unfold m a b

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.

Constructors

forall s. Unfold (s -> m (Step s b)) (a -> m s)

Unfold step inject

Instances

Functor m => Functor (Unfold m a)

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

Defined in Streamly.Internal.Data.Unfold.Type

Methods

fmap :: (a0 -> b) -> Unfold m a a0 -> Unfold m a b

(<$) :: a0 -> Unfold m a b -> Unfold m a a0

Basic Constructors

mkUnfoldM :: (s -> m (Step s b)) -> (a -> m s) -> Unfold m a b

Make an unfold from step and inject functions.

Pre-release

mkUnfoldrM :: Applicative m => (a -> m (Step a b)) -> Unfold m a b

Make an unfold from a step function.

See also: unfoldrM

Pre-release

unfoldrM :: Applicative m => (a -> m (Maybe (b, a))) -> Unfold m a b

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.

unfoldr :: Applicative m => (a -> Maybe (b, a)) -> Unfold m a b

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]

functionM :: Applicative m => (a -> m b) -> Unfold m a b

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

function :: Applicative m => (a -> b) -> Unfold m a b

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

function f = functionM $ return . f

identity :: Applicative m => Unfold m a a

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

identity = function Prelude.id

Pre-release

From Values

fromEffect :: Applicative m => m b -> Unfold m a b

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

Pre-release

fromPure :: Applicative m => b -> Unfold m a b

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

fromPure = fromEffect . pure

Pre-release

From Containers

fromList :: Applicative m => Unfold m [a] a

Convert a list of pure values to a Stream

Transformations

lmap :: (a -> c) -> Unfold m c b -> Unfold m a b

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)

lmapM :: Monad m => (a -> m c) -> Unfold m c b -> Unfold m a b

Map an action on the input argument of the Unfold.

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

map :: Functor m => (b -> c) -> Unfold m a b -> Unfold m a c

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

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

Pre-release

map2 :: Functor m => (a -> b -> c) -> Unfold m a b -> Unfold m a c

>>> 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.

mapM :: Monad m => (b -> m c) -> Unfold m a b -> Unfold m a c

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)

mapM2 :: Monad m => (a -> b -> m c) -> Unfold m a b -> Unfold m a c

both :: a -> Unfold m a b -> Unfold m Void b

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

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

Pre-release

first :: a -> Unfold m (a, b) c -> Unfold m b c

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

second :: b -> Unfold m (a, b) c -> Unfold m a c

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

Trimming

takeWhileMWithInput :: Monad m => (a -> b -> m Bool) -> Unfold m a b -> Unfold m a b

takeWhileM :: Monad m => (b -> m Bool) -> Unfold m a b -> Unfold m a b

Same as takeWhile but with a monadic predicate.

takeWhile :: Monad m => (b -> Bool) -> Unfold m a b -> Unfold m a b

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

Nesting

data ConcatState s1 s2

Constructors

ConcatOuter s1

ConcatInner s1 s2

many :: Monad m => Unfold m b c -> Unfold m a b -> Unfold m a c

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)

many2 :: Monad m => Unfold m (a, b) c -> Unfold m a b -> Unfold m a c

manyInterleave :: Monad m => Unfold m a b -> Unfold m c a -> Unfold m c b

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

crossApplySnd :: Unfold m a b -> Unfold m a c -> Unfold m a c

Outer product discarding the first element.

Unimplemented

crossApplyFst :: Unfold m a b -> Unfold m a c -> Unfold m a b

Outer product discarding the second element.

Unimplemented

crossWithM :: Monad m => (b -> c -> m d) -> Unfold m a b -> Unfold m a c -> Unfold m a d

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

crossWith :: Monad m => (b -> c -> d) -> Unfold m a b -> Unfold m a c -> Unfold m a d

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)]

cross :: Monad m => Unfold m a b -> Unfold m a c -> Unfold m a (b, c)

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

crossApply :: Monad m => Unfold m a (b -> c) -> Unfold m a b -> Unfold m a c

concatMapM :: Monad m => (b -> m (Unfold m a c)) -> Unfold m a b -> Unfold m a c

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

concatMap :: Monad m => (b -> Unfold m a c) -> Unfold m a b -> Unfold m a c

bind :: Monad m => Unfold m a b -> (b -> Unfold m a c) -> Unfold m a c infixl 1

zipWithM :: Monad m => (b -> c -> m d) -> Unfold m a b -> Unfold m a c -> Unfold m a d

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

zipWith :: Monad m => (b -> c -> d) -> Unfold m a b -> Unfold m a c -> Unfold m a d

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)

Unfolds

Basic Constructors

nilM :: Applicative m => (a -> m c) -> Unfold m a b

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

nil :: Applicative m => Unfold m a b

An empty stream.

consM :: Applicative m => (a -> m b) -> Unfold m a b -> Unfold m a b

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

Generators

Generate a monadic stream from a seed.

repeatM :: Applicative m => Unfold m (m a) a

Generates an infinite stream repeating the seed.

replicateM :: Applicative m => Unfold m (Int, m a) a

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

fromIndicesM :: Applicative m => (Int -> m a) -> Unfold m Int a

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

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

Pre-release

iterateM :: Applicative m => (a -> m a) -> Unfold m (m a) a

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

Enumerations

class Enum a => Enumerable a where

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

Methods

enumerateFrom :: Monad m => Unfold m a a

Unfolds from generating a stream starting with the element from, enumerating up to maxBound when the type is Bounded or generating an infinite stream when the type is not Bounded.

>>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFrom (0 :: Int)
[0,1,2,3]

For Fractional types, enumeration is numerically stable. However, no overflow or underflow checks are performed.

>>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFrom 1.1
[1.1,2.1,3.1,4.1]

Pre-release

enumerateFromTo :: Monad m => Unfold m (a, a) a

Unfolds (from, to) generating a finite stream starting with the element from, enumerating the type up to the value to. If to is smaller than from then an empty stream is returned.

>>> Stream.toList $ Stream.unfold Unfold.enumerateFromTo (0, 4)
[0,1,2,3,4]

For Fractional types, the last element is equal to the specified to value after rounding to the nearest integral value.

>>> Stream.toList $ Stream.unfold Unfold.enumerateFromTo (1.1, 4)
[1.1,2.1,3.1,4.1]

>>> Stream.toList $ Stream.unfold Unfold.enumerateFromTo (1.1, 4.6)
[1.1,2.1,3.1,4.1,5.1]

Pre-release

enumerateFromThen :: Monad m => Unfold m (a, a) a

Unfolds (from, then) generating a stream whose first element is from and the successive elements are in increments of then. Enumeration can occur downwards or upwards depending on whether then comes before or after from. For Bounded types the stream ends when maxBound is reached, for unbounded types it keeps enumerating infinitely.

>>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFromThen (0, 2)
[0,2,4,6]

>>> Stream.toList $ Stream.take 4 $ Stream.unfold Unfold.enumerateFromThen (0,(-2))
[0,-2,-4,-6]

Pre-release

enumerateFromThenTo :: Monad m => Unfold m (a, a, a) a

Unfolds (from, then, to) generating a finite stream whose first element is from and the successive elements are in increments of then up to to. Enumeration can occur downwards or upwards depending on whether then comes before or after from.

>>> Stream.toList $ Stream.unfold Unfold.enumerateFromThenTo (0, 2, 6)
[0,2,4,6]

>>> Stream.toList $ Stream.unfold Unfold.enumerateFromThenTo (0, (-2), (-6))
[0,-2,-4,-6]

Pre-release

Instances

Enumerable Int16

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Int16 Int16

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int16, Int16) Int16

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Int16, Int16) Int16

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int16, Int16, Int16) Int16

Enumerable Int32

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Int32 Int32

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int32, Int32) Int32

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Int32, Int32) Int32

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int32, Int32, Int32) Int32

Enumerable Int64

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Int64 Int64

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int64, Int64) Int64

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Int64, Int64) Int64

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int64, Int64, Int64) Int64

Enumerable Int8

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Int8 Int8

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int8, Int8) Int8

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Int8, Int8) Int8

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int8, Int8, Int8) Int8

Enumerable Word16

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Word16 Word16

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word16, Word16) Word16

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Word16, Word16) Word16

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word16, Word16, Word16) Word16

Enumerable Word32

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Word32 Word32

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word32, Word32) Word32

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Word32, Word32) Word32

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word32, Word32, Word32) Word32

Enumerable Word64

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Word64 Word64

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word64, Word64) Word64

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Word64, Word64) Word64

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word64, Word64, Word64) Word64

Enumerable Ordering

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Ordering Ordering

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Ordering, Ordering) Ordering

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Ordering, Ordering) Ordering

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Ordering, Ordering, Ordering) Ordering

Enumerable Word8

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Word8 Word8

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word8, Word8) Word8

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Word8, Word8) Word8

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word8, Word8, Word8) Word8

Enumerable Integer

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Integer Integer

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Integer, Integer) Integer

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Integer, Integer) Integer

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Integer, Integer, Integer) Integer

Enumerable Natural

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Natural Natural

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Natural, Natural) Natural

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Natural, Natural) Natural

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Natural, Natural, Natural) Natural

Enumerable ()

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m () ()

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m ((), ()) ()

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m ((), ()) ()

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m ((), (), ()) ()

Enumerable Bool

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Bool Bool

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Bool, Bool) Bool

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Bool, Bool) Bool

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Bool, Bool, Bool) Bool

Enumerable Char

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Char Char

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Char, Char) Char

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Char, Char) Char

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Char, Char, Char) Char

Enumerable Double

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Double Double

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Double, Double) Double

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Double, Double) Double

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Double, Double, Double) Double

Enumerable Float

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Float Float

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Float, Float) Float

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Float, Float) Float

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Float, Float, Float) Float

Enumerable Int

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Int Int

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int, Int) Int

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Int, Int) Int

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Int, Int, Int) Int

Enumerable Word

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m Word Word

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word, Word) Word

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Word, Word) Word

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Word, Word, Word) Word

Enumerable a => Enumerable (Identity a)

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m (Identity a) (Identity a)

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Identity a, Identity a) (Identity a)

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Identity a, Identity a) (Identity a)

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Identity a, Identity a, Identity a) (Identity a)

Integral a => Enumerable (Ratio a)

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m (Ratio a) (Ratio a)

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Ratio a, Ratio a) (Ratio a)

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Ratio a, Ratio a) (Ratio a)

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Ratio a, Ratio a, Ratio a) (Ratio a)

HasResolution a => Enumerable (Fixed a)

Defined in Streamly.Internal.Data.Unfold.Enumeration

Methods

enumerateFrom :: forall (m :: Type -> Type). Monad m => Unfold m (Fixed a) (Fixed a)

enumerateFromTo :: forall (m :: Type -> Type). Monad m => Unfold m (Fixed a, Fixed a) (Fixed a)

enumerateFromThen :: forall (m :: Type -> Type). Monad m => Unfold m (Fixed a, Fixed a) (Fixed a)

enumerateFromThenTo :: forall (m :: Type -> Type). Monad m => Unfold m (Fixed a, Fixed a, Fixed a) (Fixed a)

Enumerating Num Types

enumerateFromStepNum :: (Monad m, Num a) => Unfold m (a, a) a

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

enumerateFromNum :: (Monad m, Num a) => Unfold m a a

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

enumerateFromThenNum :: (Monad m, Num a) => Unfold m (a, a) a

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

Enumerating unbounded Integral Types

enumerateFromStepIntegral :: (Monad m, Integral a) => Unfold m (a, a) a

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

Internal

enumerateFromIntegral :: (Monad m, Integral a) => Unfold m a a

enumerateFromThenIntegral :: (Monad m, Integral a) => Unfold m (a, a) a

enumerateFromToIntegral :: (Monad m, Integral a) => Unfold m (a, a) a

enumerateFromThenToIntegral :: (Monad m, Integral a) => Unfold m (a, a, a) a

Enumerating Bounded Integral Types

enumerateFromIntegralBounded :: (Monad m, Integral a, Bounded a) => Unfold m a a

enumerateFromThenIntegralBounded :: (Monad m, Integral a, Bounded a) => Unfold m (a, a) a

enumerateFromToIntegralBounded :: (Monad m, Integral a, Bounded a) => Unfold m (a, a) a

enumerateFromThenToIntegralBounded :: (Monad m, Integral a, Bounded a) => Unfold m (a, a, a) a

Enumerating small Integral Types

Small types are always bounded.

enumerateFromSmallBounded :: (Monad m, Enum a, Bounded a) => Unfold m a a

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

Internal

enumerateFromThenSmallBounded :: forall m a. (Monad m, Enum a, Bounded a) => Unfold m (a, a) a

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

Internal

enumerateFromToSmall :: (Monad m, Enum a) => Unfold m (a, a) a

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

Internal

enumerateFromThenToSmall :: (Monad m, Enum a) => Unfold m (a, a, a) a

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

Enumerating Fractional Types

Enumeration of Num specialized to Fractional types.

enumerateFromFractional :: (Monad m, Fractional a) => Unfold m a a

enumerateFromThenFractional :: (Monad m, Fractional a) => Unfold m (a, a) a

enumerateFromToFractional :: (Monad m, Fractional a, Ord a) => Unfold m (a, a) a

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

enumerateFromThenToFractional :: (Monad m, Fractional a, Ord a) => Unfold m (a, a, a) a

From Containers

fromListM :: Applicative m => Unfold m [m a] a

Convert a list of monadic values to a Stream

From Memory

fromPtr :: forall m a. (MonadIO m, Storable a) => Unfold m (Ptr a) a

From Stream

fromStreamK :: Applicative m => Unfold m (StreamK m a) a

fromStreamD :: Applicative m => Unfold m (Stream m a) a

fromStream :: Applicative m => Unfold m (Stream m a) a

Combinators

Mapping on Input

discardFirst :: Unfold m a b -> Unfold m (c, a) b

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

discardSecond :: Unfold m a b -> Unfold m (a, c) b

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

swap :: Unfold m (a, c) b -> Unfold m (c, a) b

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

Folding

fold :: Monad m => Fold m b c -> Unfold m a b -> a -> m c

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

Mapping on Output

postscanlM' :: Monad m => (b -> a -> m b) -> m b -> Unfold m c a -> Unfold m c b

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

Pre-release

postscan :: Monad m => Fold m b c -> Unfold m a b -> Unfold m a c

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

Pre-release

scan :: Monad m => Fold m b c -> Unfold m a b -> Unfold m a c

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

scanMany :: Monad m => Fold m b c -> Unfold m a b -> Unfold m a c

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

foldMany :: Monad m => Fold m b c -> Unfold m a b -> Unfold m a c

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

Pre-release

Either Wrapped Input

either :: Applicative m => Unfold m a c -> Unfold m b c -> Unfold m (Either a b) c

Choose left or right unfold based on an either input.

Pre-release

Filtering

take :: Applicative m => Int -> Unfold m a b -> Unfold m a b

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

filter :: Monad m => (b -> Bool) -> Unfold m a b -> Unfold m a b

Include only those elements that pass a predicate.

filterM :: Monad m => (b -> m Bool) -> Unfold m a b -> Unfold m a b

Same as filter but with a monadic predicate.

drop :: Applicative m => Int -> Unfold m a b -> Unfold m a b

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

dropWhile :: Monad m => (b -> Bool) -> Unfold m a b -> Unfold m a b

Similar to dropWhileM but with a pure condition function.

dropWhileM :: Monad m => (b -> m Bool) -> Unfold m a b -> Unfold m a b

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

Cross product

joinInnerGeneric :: Monad m => (b -> c -> Bool) -> Unfold m a b -> Unfold m a c -> Unfold m a (b, c)

Resource Management

bracket is the most general resource management operation, all other operations can be expressed using it. These functions have IO suffix because the allocation and cleanup functions are IO actions. For generalized allocation and cleanup functions see the functions without the IO suffix in the "streamly" package.

gbracket_

Arguments

:: Monad m

=> (a -> m c)

before

-> (forall s. m s -> m (Either e s))

try (exception handling)

-> (c -> m d)

after, on normal stop

-> Unfold m (c, e) b

on exception

-> Unfold m c b

unfold to run

-> Unfold m a b

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

gbracketIO

Arguments

:: MonadIO m

=> (a -> IO c)

before

-> (c -> IO d)

after, on normal stop, or GC

-> (c -> IO ())

action on exception

-> Unfold m e b

stream on exception

-> (forall s. m s -> IO (Either e s))

try (exception handling)

-> Unfold m c b

unfold to run

-> Unfold m a b

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

before :: (a -> m c) -> Unfold m a b -> Unfold m a b

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

afterIO :: MonadIO m => (a -> IO c) -> Unfold m a b -> Unfold m a b

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

after_ :: Monad m => (a -> m c) -> Unfold m a b -> Unfold m a b

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

finallyIO :: (MonadIO m, MonadCatch m) => (a -> IO c) -> Unfold m a b -> Unfold m a b

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

finally_ :: MonadCatch m => (a -> m c) -> Unfold m a b -> Unfold m a b

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

bracketIO :: (MonadIO m, MonadCatch m) => (a -> IO c) -> (c -> IO d) -> Unfold m c b -> Unfold m a b

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

bracket_ :: MonadCatch m => (a -> m c) -> (c -> m d) -> Unfold m c b -> Unfold m a b

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

Exceptions

Most of these combinators inhibit stream fusion, therefore, when possible, they should be called in an outer loop to mitigate the cost. For example, instead of calling them on a stream of chars call them on a stream of arrays before flattening it to a stream of chars.

onException :: MonadCatch m => (a -> m c) -> Unfold m a b -> Unfold m a b

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

handle :: (MonadCatch m, Exception e) => Unfold m e b -> Unfold m a b -> Unfold m a b

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

Inhibits stream fusion

Pre-release