git.iko.soy/streamly
on 79df417 help sign in
streamly/core/src/Streamly/Data/StreamK.hs
193 lines 5.9 kB history raw
1{-# LANGUAGE CPP #-}
2-- |
3-- Module : Streamly.Data.StreamK
4-- Copyright : (c) 2017 Composewell Technologies
5--
6-- License : BSD3
7-- Maintainer : streamly@composewell.com
8-- Stability : released
9-- Portability : GHC
10--
11-- Streams represented as chains of functions calls using Continuation Passing
12-- Style (CPS), suitable for dynamically composing potentially large number of
13-- streams.
14--
15-- Unlike the statically fused operations in "Streamly.Data.Stream", StreamK
16-- operations are less efficient, involving a function call overhead for each
17-- element, but they exhibit linear O(n) time complexity wrt to the number of
18-- stream compositions. Therefore, they are suitable for dynamically composing
19-- streams e.g. appending potentially infinite streams in recursive loops.
20-- While fused streams can be used to efficiently process elements as small as
21-- a single byte, CPS streams are typically used on bigger chunks of data to
22-- avoid the larger overhead per element. For more details See the @Stream vs
23-- StreamK@ section in the "Streamly.Data.Stream" module.
24--
25-- In addition to the combinators in this module, you can use operations from
26-- "Streamly.Data.Stream" for StreamK as well by converting StreamK to Stream
27-- ('toStream'), and vice-versa ('fromStream'). Please refer to
28-- "Streamly.Internal.Data.StreamK" for more functions that have not yet been
29-- released.
30--
31-- For documentation see the corresponding combinators in
32-- "Streamly.Data.Stream". Documentation has been omitted in this module unless
33-- there is a difference worth mentioning or if the combinator does not exist
34-- in "Streamly.Data.Stream".
36-- Notes:
37--
38-- primitive/open loop operations that can be used recursively e.g. uncons,
39-- foldBreak, parseBreak should not be converted from StreamD for use in
40-- StreamK, instead native StreamK impl should be used.
41--
42-- Closed loop operations like repeat, replicate, iterate etc can be converted
43-- from StreamD.
44--
45-- In the last phase any operation like (toStreamK . f . toStreamD) should be
46-- rewritten to a K version of f.
47-- XXX Need to add rewrite rules for all missing StreamD operations.
48--
49module Streamly.Data.StreamK
50 (
51 -- * Setup
52 -- | To execute the code examples provided in this module in ghci, please
53 -- run the following commands first.
54 --
55 -- $setup
57 -- * Overview
58 -- $overview
60 -- * Type
61 StreamK
63 -- * Construction
64 -- ** Primitives
65 -- | Primitives to construct a stream from pure values or monadic actions.
66 -- All other stream construction and generation combinators described later
67 -- can be expressed in terms of these primitives. However, the special
68 -- versions provided in this module can be much more efficient in some
69 -- cases. Users can create custom combinators using these primitives.
70 , nil
71 , nilM
72 , cons
73 , consM
75 -- ** From Values
76 , fromPure
77 , fromEffect
79 -- ** From Stream
80 -- | Please note that 'Stream' type does not observe any exceptions from
81 -- the consumer of the stream whereas 'StreamK' does.
82 , fromStream
83 , toStream
85 -- ** From Containers
86 , fromFoldable
88 -- * Elimination
90 -- ** Primitives
91 , uncons
92 , drain
94 -- -- ** Folding
95 -- , foldBreak
97 -- ** Parsing
98 -- , parseBreak
99 , parseBreakChunks
100 , parseChunks
102 -- * Transformation
103 , mapM
104 , dropWhile
105 , take
107 -- * Combining Two Streams
108 -- | Unlike the operations in "Streamly.Data.Stream", these operations can
109 -- be used to dynamically compose large number of streams e.g. using the
110 -- 'concatMapWith' and 'mergeMapWith' operations. They have a linear O(n)
111 -- time complexity wrt to the number of streams being composed.
113 -- ** Appending
114 , append
116 -- ** Interleaving
117 , interleave
119 -- ** Merging
120 , mergeBy
121 , mergeByM
123 -- ** Zipping
124 , zipWith
125 , zipWithM
127 -- ** Cross Product
128 -- XXX is "bind/concatFor" better to have than crossWith?
129 -- crossWith f xs1 xs2 = concatFor xs1 (\x -> fmap (f x) xs2)
130 , crossWith
131 -- , cross
132 -- , joinInner
133 -- , CrossStreamK (..)
135 -- * Stream of streams
136 -- | Some useful idioms:
137 --
138 -- >>> concatFoldableWith f = Prelude.foldr f StreamK.nil
139 -- >>> concatMapFoldableWith f g = Prelude.foldr (f . g) StreamK.nil
140 -- >>> concatForFoldableWith f xs g = Prelude.foldr (f . g) StreamK.nil xs
141 --
142 , concatEffect
143 -- , concatMap
144 , concatMapWith
145 , mergeMapWith
147 -- * Buffered Operations
148 , reverse
149 , sortBy
151 -- * Exceptions
152 -- | Please note that 'Stream' type does not observe any exceptions from
153 -- the consumer of the stream whereas 'StreamK' does.
154 , handle
156 -- * Resource Management
157 -- | Please note that 'Stream' type does not observe any exceptions from
158 -- the consumer of the stream whereas 'StreamK' does.
159 , bracketIO
160 )
161where
163import Streamly.Internal.Data.StreamK
164import Prelude hiding (reverse, zipWith, mapM, dropWhile, take)
166#include "DocTestDataStreamK.hs"
168-- $overview
169--
170-- Continuation passing style (CPS) stream implementation. The 'K' in 'StreamK'
171-- stands for Kontinuation.
172--
173-- StreamK can be constructed like lists, except that they use 'nil' instead of
174-- '[]' and 'cons' instead of ':'.
175--
176-- `cons` adds a pure value at the head of the stream:
177--
178-- >>> import Streamly.Data.StreamK (StreamK, cons, consM, nil)
179-- >>> stream = 1 `cons` 2 `cons` nil :: StreamK IO Int
180--
181-- You can use operations from "Streamly.Data.Stream" for StreamK as well by
182-- converting StreamK to Stream ('toStream'), and vice-versa ('fromStream').
183--
184-- >>> Stream.fold Fold.toList $ StreamK.toStream stream -- IO [Int]
185-- [1,2]
186--
187-- `consM` adds an effect at the head of the stream:
188--
189-- >>> stream = effect 1 `consM` effect 2 `consM` nil
190-- >>> Stream.fold Fold.toList $ StreamK.toStream stream
191-- 1
192-- 2
193-- [1,2]