@@ -15,37 +15,39 @@
1515-- Stability : experimental
1616-- Portability : GHC
1717--
18−-- This module is the consumer side dual of the "Streamly.Prelude" module. The
19−-- "Streamly.Prelude" module contains producer or stream generation side
20−-- compositions while this module contains consumer side or stream fold
21−-- composition. Both the modules are organized in the same way so that you can
22−-- easily find the corresponding operations.
23−--
24−-- Stream consumers are essentially left folds that can be composed in many
25−-- interesting ways. For example, a parsing applicative composition builds an
26−-- applicative parser, a distributing applicative fold composition distributes
27−-- the input to the constituent folds and then combines the outputs.
28−-- Similarly, a partitioning applicative can partition the input among the
29−-- constituent folds. There are many other ways to combine folds.
30−--
31−-- All combinators in this module are of true streaming nature. For example,
32−-- the splitting combinators accept a fold which consumes the elements in the
33−-- split segments as soon as they are generated by the producer, segments are
34−-- not buffered in memory, resulting in constant memory usage. The folds used
35−-- in these combinators can be considered as continuations.
18+-- A left fold consumes a stream and reduces it to a single value. Using the
19+-- fold combinators in "Streamly.Prelude" module only one fold operation can be
20+-- applied to a stream. This module provides a 'Fold' type that represents a
21+-- left fold. Multiple such folds can be combined in different ways; a stream
22+-- can then be supplied to the combined fold.
23+-- For example, a distributive applicative composition distributes the input to
24+-- the constituent folds and then combines the fold outputs. Similarly, a
25+-- partitioning composition can partition the input among constituent folds.
26+-- All the combinators in this module are of true streaming nature, stream
27+-- elements are not unnecessarily buffered in memory, guaranteeing a constant
28+-- memory consumption.
29+--
30+-- Consider this module as the consumer side dual of the "Streamly.Prelude"
31+-- module. "Streamly.Prelude" provides combinators that can combine stream
32+-- sources in interesting ways whereas this module provides combinators that
33+-- combine stream consumers in interesting ways. In other words,
34+-- "Streamly.Prelude" provides stream merging capabilities while
35+-- "Streamly.Fold" provides stream splitting capabilities. Both the modules
36+-- are organized in the same way so that you can easily find the corresponding
37+-- operations.
3638--
3739-- > import qualified Streamly.Fold as FL
3840--
39−--
4041-- A left fold is represented by the type 'Fold'. @Fold m a b@ folds an
4142-- input stream consisting of values of type @a@ to a structure of type
42−-- @b@. The fold can be run using 'foldl'' and an input stream.
43+-- @b@. The fold can be run using the 'foldl'' combinator and an input stream.
4344--
4445-- >>> FL.foldl' FL.sum (S.enumerateFromTo 1 100)
4546-- 5050
4647
4748-- Also see the "Streamly.Sink" module that provides specialized left folds
4849-- that discard the outputs.
50+--
4951-- IMPORTANT: keep the signatures consistent with the folds in Streamly.Prelude
5052
5153module Streamly.Fold
@@ -84,7 +86,8 @@ module Streamly.Fold
8486
8587 -- ** Full Folds (To Containers)
8688 -- | Avoid using these folds in scalable or performance critical
87− -- applications, they buffer all the input in memory.
89+ -- applications, they buffer all the input in GC memory which can be
90+ -- detrimental to performance if the input is large.
8891
8992 , toStream -- experimental
9093 , toStreamRev -- experimental
@@ -318,7 +321,7 @@ module Streamly.Fold
318321 -- * Nested Folds
319322 -- , concatMap
320323 -- , chunksOf
321− , duplicate -- experimental
324+ -- , duplicate -- experimental
322325
323326 {-
324327 -- * Windowed Classification
@@ -467,8 +470,7 @@ foldl' (Fold step begin done) = P.foldlMx' step begin done
467470-- Transformations on fold inputs
468471------------------------------------------------------------------------------
469472
470−-- | Convert a fold that generates a monadic action to a fold that generates
471−-- the output of that monadic action.
473+-- | Flatten the monadic output of a fold to pure output.
472474--
473475-- @since 0.7.0
474476{-# INLINE sequence #-}
@@ -479,8 +481,7 @@ sequence (Fold step initial extract) = Fold step initial extract'
479481 act <- extract x
480482 act >>= return
481483
482−-- | Convert a fold that generates a monadic action to a fold that generates
483−-- the output of that monadic action.
484+-- | Map a monadic function on the output of a fold.
484485--
485486-- @since 0.7.0
486487{-# INLINE mapM #-}
@@ -588,6 +589,8 @@ drain = Fold step begin done
588589--
589590-- Drain all input after passing it through a monadic function. This is the
590591-- dual of mapM_ on stream producers.
592+--
593+-- @since 0.7.0
591594{-# INLINABLE drainBy #-}
592595drainBy :: Monad m => (a -> m b) -> Fold m a ()
593596drainBy f = Fold (const (void . f)) (return ()) return
@@ -663,6 +666,8 @@ maximum :: (Monad m, Ord a) => Fold m a (Maybe a)
663666maximum = _Fold1 max
664667
665668-- | Computes the minimum element with respect to the given comparison function
669+--
670+-- @since 0.7.0
666671{-# INLINABLE minimumBy #-}
667672minimumBy :: Monad m => (a -> a -> Ordering) -> Fold m a (Maybe a)
668673minimumBy cmp = _Fold1 min'
@@ -1080,8 +1085,8 @@ ltakeWhile predicate (Fold step initial done) = Fold step' initial' done'
10801085--
10811086
10821087-- | @splitAt n f1 f2@ composes folds @f1@ and @f2@ such that first @n@
1083−-- elements of its input are sent to fold @f1@ and the rest of the stream is
1084−-- sent to fold @f2@.
1088+-- elements of its input are consumed by fold @f1@ and the rest of the stream
1089+-- is consumed by fold @f2@.
10851090--
10861091-- > let splitAt_ n xs = FL.foldl' (FL.splitAt n FL.toList FL.toList) $ S.fromList xs
10871092--
@@ -1248,10 +1253,9 @@ _spanBy cmp (Fold stepL initialL extractL) (Fold stepR initialR extractR) =
12481253
12491254 extract (Tuple3' a b _) = (,) <$> extractL a <*> extractR b
12501255
1251−-- | Span as long as the predicate is 'True'. @span p f1 f2@ composes folds
1252−-- @f1@ and @f2@ such that the composed fold continues sending the input to
1253−-- @f1@ as long as the predicate @p@ is 'True'. The rest of the input is sent
1254−-- to @f2@.
1256+-- | @span p f1 f2@ composes folds @f1@ and @f2@ such that @f1@ consumes the
1257+-- input as long as the predicate @p@ is 'True'. @f2@ consumes the rest of the
1258+-- input.
12551259--
12561260-- > let span_ p xs = FL.foldl' (FL.span p FL.toList FL.toList) $ S.fromList xs
12571261--
@@ -1264,10 +1268,10 @@ _spanBy cmp (Fold stepL initialL extractL) (Fold stepR initialR extractR) =
12641268-- >>> span_ (< 4) [1,2,3]
12651269-- > ([1,2,3],[])
12661270--
1271+-- @since 0.7.0
1272+
12671273-- This can be considered as a two-fold version of 'ltakeWhile' where we take
12681274-- both the segments instead of discarding the leftover.
1269−--
1270−-- @since 0.7.0
12711275{-# INLINE span #-}
12721276span
12731277 :: Monad m
@@ -1292,8 +1296,8 @@ span p (Fold stepL initialL extractL) (Fold stepR initialR extractR) =
12921296-- > break p = span (not . p)
12931297--
12941298-- Break as soon as the predicate becomes 'True'. @break p f1 f2@ composes
1295−-- folds @f1@ and @f2@ such that @f1@ stops receiving input as soon as the
1296−-- predicate @p@ becomes 'True'. The rest of the input is sent to @f2@.
1299+-- folds @f1@ and @f2@ such that @f1@ stops consuming input as soon as the
1300+-- predicate @p@ becomes 'True'. The rest of the input is consumed @f2@.
12971301--
12981302-- This is the binary version of 'splitBy'.
12991303--
@@ -2244,9 +2248,9 @@ unzip = unzipWith id
22442248-- > 465
22452249--
22462250-- @since 0.7.0
2247−{-# INLINABLE duplicate #-}
2248−duplicate :: Applicative m => Fold m a b -> Fold m a (Fold m a b)
2249−duplicate (Fold step begin done) =
2251+{-# INLINABLE _duplicate #-}
2252+_duplicate :: Applicative m => Fold m a b -> Fold m a (Fold m a b)
2253+_duplicate (Fold step begin done) =
22502254 Fold step begin (\x -> pure (Fold step (pure x) done))
22512255
22522256{-