git.iko.soy/streamly
on 6f4fd8d help sign in
streamly/src/Streamly/Data/Unfold.hs
62 lines 2.7 kB history raw
1#include "inline.hs"
3-- |
4-- Module : Streamly.Data.Unfold
5-- Copyright : (c) 2019 Composewell Technologies
6-- License : BSD3
7-- Maintainer : streamly@composewell.com
8-- Stability : experimental
9-- Portability : GHC
10--
11-- 'Unfold' type represents an effectful action that generates a stream of
12-- values from a single starting value often called a seed value. Values can be
13-- generated and /pulled/ from the 'Unfold' one at a time. It can also be
14-- called a producer or a source of stream. It is a data representation of the
15-- standard 'Streamly.Prelude.unfoldr' function. An 'Unfold' can be converted
16-- into a stream type using 'Streamly.Prelude.unfold' by supplying the seed.
17--
18-- = Performance Notes
19--
20-- 'Unfold' representation is more efficient than using streams when combining
21-- streams. 'Unfold' type allows multiple unfold actions to be composed into a
22-- single unfold function in an efficient manner by enabling the compiler to
23-- perform stream fusion optimization.
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.concatUnfold'.
34--
35-- On the other hand, transformation operations on stream types are as
36-- efficient as transformations on 'Unfold'.
37--
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
42-- streams.
43--
44-- = Programmer Notes
45--
46-- > import qualified Streamly.Data.Unfold as UF
47--
48-- More, not yet exposed, unfold combinators can be found in
49-- "Streamly.Internal.Data.Unfold".
51-- The stream types (e.g. t'Streamly.SerialT') can be considered as a special
52-- case of 'Unfold' with no starting seed.
53--
54module Streamly.Data.Unfold
55 (
56 -- * Unfold Type
57 Unfold
58 )
59where
61import Prelude hiding (concat, map, takeWhile, take, filter, const)
62import Streamly.Internal.Data.Unfold