git.iko.soy/streamly
on f39b982 help sign in
streamly/src/Streamly/Data/Unfold.hs
69 lines 2.9 kB history raw
1{-# LANGUAGE CPP #-}
2{-# LANGUAGE ExistentialQuantification #-}
3{-# LANGUAGE FlexibleContexts #-}
4{-# LANGUAGE PatternSynonyms #-}
5{-# LANGUAGE RankNTypes #-}
6{-# LANGUAGE ScopedTypeVariables #-}
8#include "inline.hs"
10-- |
11-- Module : Streamly.Data.Unfold
12-- Copyright : (c) 2019 Composewell Technologies
13-- License : BSD3
14-- Maintainer : streamly@composewell.com
15-- Stability : experimental
16-- Portability : GHC
17--
18-- 'Unfold' type represents an effectful action that generates a stream of
19-- values from a single starting value often called a seed value. Values can be
20-- generated and /pulled/ from the 'Unfold' one at a time. It can also be
21-- called a producer or a source of stream. It is a data representation of the
22-- standard 'Streamly.Prelude.unfoldr' function. An 'Unfold' can be converted
23-- into a stream type using 'Streamly.Prelude.unfold' by supplying the seed.
24--
25-- = Performance Notes
26--
27-- 'Unfold' representation is more efficient than using streams when combining
28-- streams. 'Unfold' type allows multiple unfold actions to be composed into a
29-- single unfold function in an efficient manner by enabling the compiler to
30-- perform stream fusion optimization.
31-- @Unfold m a b@ can be considered roughly equivalent to an action @a -> t m
32-- b@ (where @t@ is a stream type). Instead of using an 'Unfold' one could just
33-- use a function of the shape @a -> t m b@. However, working with stream types
34-- like t'Streamly.SerialT' does not allow the compiler to perform stream fusion
35-- optimization when merging, appending or concatenating multiple streams.
36-- Even though stream based combinator have excellent performance, they are
37-- much less efficient when compared to combinators using 'Unfold'. For
38-- example, the 'Streamly.Prelude.concatMap' combinator which uses @a -> t m b@
39-- (where @t@ is a stream type) to generate streams is much less efficient
40-- compared to 'Streamly.Prelude.concatUnfold'.
41--
42-- On the other hand, transformation operations on stream types are as
43-- efficient as transformations on 'Unfold'.
44--
45-- We should note that in some cases working with stream types may be more
46-- convenient compared to working with the 'Unfold' type. However, if extra
47-- performance boost is important then 'Unfold' based composition should be
48-- preferred compared to stream based composition when merging or concatenating
49-- streams.
50--
51-- = Programmer Notes
52--
53-- > import qualified Streamly.Data.Unfold as UF
54--
55-- More, not yet exposed, unfold combinators can be found in
56-- "Streamly.Internal.Data.Unfold".
58-- The stream types (e.g. t'Streamly.SerialT') can be considered as a special
59-- case of 'Unfold' with no starting seed.
60--
61module Streamly.Data.Unfold
62 (
63 -- * Unfold Type
64 Unfold
65 )
66where
68import Prelude hiding (concat, map, takeWhile, take, filter, const)
69import Streamly.Internal.Data.Unfold