git.iko.soy/streamly
on 9541caf help sign in
streamly/core/src/Streamly/Data/StreamK.hs
159 lines 3.8 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 , nil
54 , nilM
55 , cons
56 , consM
58 -- ** From Values
59 , fromPure
60 , fromEffect
62 -- ** From Stream
63 , fromStream
64 , toStream
66 -- ** From Containers
67 , fromFoldable
69 -- * Elimination
71 -- ** Primitives
72 , uncons
73 , drain
75 -- -- ** Folding
76 -- , foldBreak
78 -- ** Parsing
79 -- , parseBreak
80 , parseBreakChunks
81 , parseChunks
83 -- * Transformation
84 , mapM
85 , dropWhile
86 , take
88 -- * Combining Two Streams
89 -- ** Appending
90 , append
92 -- ** Interleaving
93 , interleave
95 -- ** Merging
96 , mergeBy
97 , mergeByM
99 -- ** Zipping
100 , zipWith
101 , zipWithM
103 -- ** Cross Product
104 -- XXX is "bind/concatFor" better to have than crossWith?
105 -- crossWith f xs1 xs2 = concatFor xs1 (\x -> fmap (f x) xs2)
106 , crossWith
107 -- , cross
108 -- , joinInner
109 -- , CrossStreamK (..)
111 -- * Stream of streams
112 , concatEffect
113 -- , concatMap
114 , concatMapWith
115 , mergeMapWith
117 -- * Buffered Operations
118 , reverse
119 , sortBy
120 )
121where
123import Streamly.Internal.Data.Stream.StreamK
124import Prelude hiding (reverse, zipWith, mapM, dropWhile, take)
126#include "DocTestDataStreamK.hs"
128-- $overview
129--
130-- Continuation passing style (CPS) stream implementation. The 'K' in 'StreamK'
131-- stands for Kontinuation.
132--
133-- StreamK can be constructed like lists, except that they use 'nil' instead of
134-- '[]' and 'cons' instead of ':'.
135--
136-- `cons` adds a pure value at the head of the stream:
137--
138-- >>> import Streamly.Data.StreamK (StreamK, cons, consM, nil)
139-- >>> stream = 1 `cons` 2 `cons` nil :: StreamK IO Int
140--
141-- You can use operations from "Streamly.Data.Stream" for StreamK as well by
142-- converting StreamK to Stream ('toStream'), and vice-versa ('fromStream').
143--
144-- >>> Stream.fold Fold.toList $ StreamK.toStream stream -- IO [Int]
145-- [1,2]
146--
147-- `consM` adds an effect at the head of the stream:
148--
149-- >>> stream = effect 1 `consM` effect 2 `consM` nil
150-- >>> Stream.fold Fold.toList $ StreamK.toStream stream
151-- 1
152-- 2
153-- [1,2]
154--
155-- == Exception Handling
156--
157-- There are no native exception handling operations in the StreamK module,
158-- please convert to 'Stream' type and use exception handling operations from
159-- "Streamly.Data.Stream".