@@ -91,31 +91,32 @@ module Streamly.Prelude
9191 , foldxM
9292
9393 -- ** Specialized Folds
94− , null
94+
95+ -- Filtering folds: extract parts of the stream
9596 , head
9697 , tail
9798 , last
9899 , init
100+
101+ -- Conditional folds: may terminate early based on a condition
102+ , null
99103 , elem
104+ , elemIndex
100105 , notElem
101− , length
106+ , lookup
107+ , find
108+ , findIndex
102109 , all
103110 , any
104111 , and
105112 , or
113+
114+ -- Full folds - need to go through all elements
115+ , length
106116 , maximum
107117 , minimum
108118 , sum
109119 , product
110− , lookup
111− , find
112−
113− -- *** Indices
114− , findIndices
115− , findIndex
116− , elemIndices
117− , elemIndex
118−
119120
120121 -- ** Map and Fold
121122 , mapM_
@@ -126,7 +127,14 @@ module Streamly.Prelude
126127 , toHandle
127128
128129 -- * Transformation
129− -- ** By folding (scans)
130+ -- ** Mapping
131+ , Serial.map
132+ , mapM
133+ , sequence
134+
135+ -- ** Scanning
136+ -- | Scan is a transformation by continuously folding the result with the
137+ -- next element of the stream.
130138 , scanl'
131139 , scanlM'
132140 , scanx
@@ -141,20 +149,19 @@ module Streamly.Prelude
141149 , dropWhile
142150 , dropWhileM
143151
144− -- ** Mapping
145− , Serial.map
146− , mapM
147− , sequence
148−
149− -- ** Map and Filter
150− , mapMaybe
151− , mapMaybeM
152+ -- ** Inserting
153+ , intersperseM
152154
153155 -- ** Reordering
154156 , reverse
155157
156− -- ** Inserting
157− , intersperseM
158+ -- ** Indices
159+ , findIndices
160+ , elemIndices
161+
162+ -- ** Map and Filter
163+ , mapMaybe
164+ , mapMaybeM
158165
159166 -- * Zipping
160167 , zipWith
@@ -303,10 +310,29 @@ unfoldrMSerial step seed = fromStreamS (S.unfoldrM step seed)
303310-- Specialized Generation
304311------------------------------------------------------------------------------
305312
313+-- Faster than yieldM because there is no bind. Usually we can construct a
314+-- stream from a pure value using "pure" in an applicative, however in case of
315+-- Zip streams pure creates an infinite stream.
316+--
317+-- | Create a singleton stream from a pure value. In monadic streams, 'pure' or
318+-- 'return' can be used in place of 'yield', however, in Zip applicative
319+-- streams 'pure' is equivalent to 'repeat'.
320+--
321+-- @since 0.4.0
306322{-# INLINE yield #-}
307323yield :: IsStream t => a -> t m a
308324yield a = K.yield a
309325
326+-- | Create a singleton stream from a monadic action. Same as @m \`consM` nil@
327+-- but more efficient.
328+--
329+-- @
330+-- > toList $ yieldM getLine
331+-- hello
332+-- ["hello"]
333+-- @
334+--
335+-- @since 0.4.0
310336{-# INLINE yieldM #-}
311337yieldM :: (Monad m, IsStream t) => m a -> t m a
312338yieldM m = K.yieldM m