@@ -8,57 +8,93 @@
8-- Stability : experimental
8-- Stability : experimental
9-- Portability : GHC
9-- Portability : GHC
11−-- 'Unfold' type represents an effectful action that generates a stream of
11+-- An 'Unfold' is a source or a producer of a stream of values. It takes a
12−-- values from a single starting value often called a seed value. Values can be
12+-- seed value as an input and unfolds it into a sequence of values.
13−-- generated and /pulled/ from the 'Unfold' one at a time. It can also be
13+--
14−-- called a producer or a source of stream. It is a data representation of the
14+-- >>> import qualified Streamly.Data.Fold as Fold
15−-- standard 'Streamly.Prelude.unfoldr' function. An 'Unfold' can be converted
15+-- >>> import qualified Streamly.Data.Unfold as Unfold
16−-- into a stream type using 'Streamly.Prelude.unfold' by supplying the seed.
16+-- >>> import qualified Streamly.Prelude as Stream
18−-- = Performance Notes
18+-- For example, the 'fromList' Unfold generates a stream of values from a
19−--
19+-- supplied list. Unfolds can be converted to 'Streamly.Prelude.SerialT'
20−-- 'Unfold' representation is more efficient than using streams when combining
20+-- stream using the Stream.unfold operation.
21−-- streams. 'Unfold' type allows multiple unfold actions to be composed into a
21+--
22−-- single unfold function in an efficient manner by enabling the compiler to
22+-- >>> stream = Stream.unfold Unfold.fromList [1..100]
23−-- perform stream fusion optimization.
23+-- >>> Stream.sum stream
24−-- @Unfold m a b@ can be considered roughly equivalent to an action @a -> t m
25−-- b@ (where @t@ is a stream type). Instead of using an 'Unfold' one could just
26−-- use a function of the shape @a -> t m b@. However, working with stream types
27−-- like t'Streamly.SerialT' does not allow the compiler to perform stream fusion
28−-- optimization when merging, appending or concatenating multiple streams.
29−-- Even though stream based combinator have excellent performance, they are
30−-- much less efficient when compared to combinators using 'Unfold'. For
31−-- example, the 'Streamly.Prelude.concatMap' combinator which uses @a -> t m b@
32−-- (where @t@ is a stream type) to generate streams is much less efficient
33−-- compared to 'Streamly.Prelude.unfoldMany'.
35−-- On the other hand, transformation operations on stream types are as
25+--
36−-- efficient as transformations on 'Unfold'.
26+-- All the serial stream generation operations in "Streamly.Prelude"
37−--
27+-- can be expressed using unfolds:
38−-- We should note that in some cases working with stream types may be more
39−-- convenient compared to working with the 'Unfold' type. However, if extra
40−-- performance boost is important then 'Unfold' based composition should be
41−-- preferred compared to stream based composition when merging or concatenating
46−-- > import qualified Streamly.Data.Unfold as UF
29+-- > Stream.fromList = Stream.unfold Unfold.fromList [1..100]
48−-- More, not yet exposed, unfold combinators can be found in
31+-- Conceptually, an 'Unfold' is just like "Data.List.unfoldr". Let us write a
49−-- "Streamly.Internal.Data.Unfold".
32+-- step function to unfold a list using "Data.List.unfoldr":
51−-- The stream types (e.g. t'Streamly.SerialT') can be considered as a special
34+-- >>> :{
52−-- case of 'Unfold' with no starting seed.
35+-- f [] = Nothing
36+-- f (x:xs) = Just (x, xs)
39+-- >>> Data.List.unfoldr f [1,2,3]
42+-- Unfold.unfoldr is just the same, it uses the same step function:
44+-- >>> Stream.toList $ Stream.unfold (Unfold.unfoldr f) [1,2,3]
47+-- The input of an unfold can be transformed using 'lmap':
49+-- >>> u = Unfold.lmap (fmap (+1)) Unfold.fromList
50+-- >>> Stream.toList $ Stream.unfold u [1..5]
53+-- 'Unfold' streams can be transformed using transformation combinators. For
54+-- example, to retain only the first two elements of an unfold:
56+-- >>> u = Unfold.take 2 Unfold.fromList
57+-- >>> Stream.toList $ Stream.unfold u [1..100]
60+-- Multiple unfolds can be combined in several interesting ways. For example,
61+-- to generate nested looping as in imperative languages (also known as cross
62+-- product of the two streams):
64+-- >>> u1 = Unfold.lmap fst Unfold.fromList
65+-- >>> u2 = Unfold.lmap snd Unfold.fromList
66+-- >>> u = Unfold.crossWith (,) u1 u2
67+-- >>> Stream.toList $ Stream.unfold u ([1,2,3], [4,5,6])
68+-- [(1,4),(1,5),(1,6),(2,4),(2,5),(2,6),(3,4),(3,5),(3,6)]
70+-- Nested loops using unfolds provide C like performance due to complete stream
73+-- Please see "Streamly.Internal.Data.Unfold" for additional @Pre-release@
76+-- = Unfolds vs. Streams
78+-- Unfolds' raison d'etre is their efficiency in nested stream operations due
79+-- to complete stream fusion. 'Streamly.Prelude.concatMap' or the 'Monad'
80+-- instance of streams use stream generation operations of the shape @a -> t m
81+-- b@ and then flatten the resulting stream. This implementation is more
82+-- powerful but does not allow for complete stream fusion. Unfolds provide
83+-- less powerful but more efficient 'Streamly.Prelude.unfoldMany', 'many' and
84+-- 'crossWith' operations as an alternative to a subset of use cases of
85+-- 'concatMap' and 'Applicative' stream operations.
87+-- "Streamly.Prelude" exports polymorphic stream generation operations that
88+-- provide the same functionality as unfolds in this module. Since unfolds can
89+-- be easily converted to streams, several modules in streamly provide only
90+-- unfolds for serial stream generation. We cannot use unfolds exclusively for
91+-- stream generation as they do not support concurrency.
54module Streamly.Data.Unfold
93module Streamly.Data.Unfold
56 -- * Unfold Type
95 -- * Unfold Type
62 -- * Unfolds
98 -- * Unfolds
63 -- One to one correspondence with
99 -- One to one correspondence with
64 -- "Streamly.Internal.Data.Stream.IsStream.Generate"
100 -- "Streamly.Internal.Data.Stream.IsStream.Generate"
@@ -106,14 +142,6 @@ module Streamly.Data.Unfold
107 -- ** Nesting
143 -- ** Nesting
110− -- ** Resource Management