git.iko.soy/streamly
on dddee88 help sign in
streamly/core/src/Streamly/Data/StreamK.hs
164 lines 4.2 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 using Continuation Passing Style (CPS). See the @Stream vs StreamK@
12-- section in the "Streamly.Data.Stream" module to know when to use this
13-- module.
14--
15-- Please refer to "Streamly.Internal.Data.Stream.StreamK" for more functions
16-- that have not yet been released.
17--
18-- Some useful idioms:
19--
20-- >>> concatFoldableWith f = Prelude.foldr f StreamK.nil
21-- >>> concatMapFoldableWith f g = Prelude.foldr (f . g) StreamK.nil
22-- >>> concatForFoldableWith f xs g = Prelude.foldr (f . g) StreamK.nil xs
24-- Notes:
25--
26-- primitive/open loop operations that can be used recursively e.g. uncons,
27-- foldBreak, parseBreak should not be converted from StreamD for use in
28-- StreamK, instead native StreamK impl should be used.
29--
30-- Closed loop operations like repeat, replicate, iterate etc can be converted
31-- from StreamD.
32--
33-- In the last phase any operation like (toStreamK . f . toStreamD) should be
34-- rewritten to a K version of f.
35-- XXX Need to add rewrite rules for all missing StreamD operations.
36--
37module Streamly.Data.StreamK
38 (
39 -- * Setup
40 -- | To execute the code examples provided in this module in ghci, please
41 -- run the following commands first.
42 --
43 -- $setup
45 -- * Overview
46 -- $overview
48 -- * Type
49 StreamK
51 -- * Construction
52 -- ** Primitives
53 -- | Primitives to construct a stream from pure values or monadic actions.
54 -- All other stream construction and generation combinators described later
55 -- can be expressed in terms of these primitives. However, the special
56 -- versions provided in this module can be much more efficient in some
57 -- cases. Users can create custom combinators using these primitives.
58 , nil
59 , nilM
60 , cons
61 , consM
63 -- ** From Values
64 , fromPure
65 , fromEffect
67 -- ** From Stream
68 , fromStream
69 , toStream
71 -- ** From Containers
72 , fromFoldable
74 -- * Elimination
76 -- ** Primitives
77 , uncons
78 , drain
80 -- -- ** Folding
81 -- , foldBreak
83 -- ** Parsing
84 -- , parseBreak
85 , parseBreakChunks
86 , parseChunks
88 -- * Transformation
89 , mapM
90 , dropWhile
91 , take
93 -- * Combining Two Streams
94 -- ** Appending
95 , append
97 -- ** Interleaving
98 , interleave
100 -- ** Merging
101 , mergeBy
102 , mergeByM
104 -- ** Zipping
105 , zipWith
106 , zipWithM
108 -- ** Cross Product
109 -- XXX is "bind/concatFor" better to have than crossWith?
110 -- crossWith f xs1 xs2 = concatFor xs1 (\x -> fmap (f x) xs2)
111 , crossWith
112 -- , cross
113 -- , joinInner
114 -- , CrossStreamK (..)
116 -- * Stream of streams
117 , concatEffect
118 -- , concatMap
119 , concatMapWith
120 , mergeMapWith
122 -- * Buffered Operations
123 , reverse
124 , sortBy
125 )
126where
128import Streamly.Internal.Data.Stream.StreamK
129import Prelude hiding (reverse, zipWith, mapM, dropWhile, take)
131#include "DocTestDataStreamK.hs"
133-- $overview
134--
135-- Continuation passing style (CPS) stream implementation. The 'K' in 'StreamK'
136-- stands for Kontinuation.
137--
138-- StreamK can be constructed like lists, except that they use 'nil' instead of
139-- '[]' and 'cons' instead of ':'.
140--
141-- `cons` adds a pure value at the head of the stream:
142--
143-- >>> import Streamly.Data.StreamK (StreamK, cons, consM, nil)
144-- >>> stream = 1 `cons` 2 `cons` nil :: StreamK IO Int
145--
146-- You can use operations from "Streamly.Data.Stream" for StreamK as well by
147-- converting StreamK to Stream ('toStream'), and vice-versa ('fromStream').
148--
149-- >>> Stream.fold Fold.toList $ StreamK.toStream stream -- IO [Int]
150-- [1,2]
151--
152-- `consM` adds an effect at the head of the stream:
153--
154-- >>> stream = effect 1 `consM` effect 2 `consM` nil
155-- >>> Stream.fold Fold.toList $ StreamK.toStream stream
156-- 1
157-- 2
158-- [1,2]
159--
160-- == Exception Handling
161--
162-- There are no native exception handling operations in the StreamK module,
163-- please convert to 'Stream' type and use exception handling operations from
164-- "Streamly.Data.Stream".