@@ -155,7 +155,7 @@ module Streamly.Internal.Data.Fold
155155
156156 -- * Running A Fold
157157 , drive
158− , driveBreak
158+ , breakStream
159159
160160 -- * Building Incrementally
161161 , extractM
@@ -165,7 +165,9 @@ module Streamly.Internal.Data.Fold
165165 , snocl
166166 , snocM
167167 , snoclM
168− , augment
168+
169+ , addOne
170+ , addStream
169171
170172 -- * Combinators
171173 -- ** Utilities
@@ -337,9 +339,11 @@ import Streamly.Internal.Data.Fold.Type
337339-- >>> :m
338340-- >>> :set -package random
339341-- >>> import Control.Monad (void)
340−-- >>> import Data.Functor.Identity (runIdentity)
342+-- >>> import Data.Functor.Identity (Identity, runIdentity)
341343-- >>> import Data.Maybe (isJust)
342344-- >>> import Data.Monoid (Last(..), Sum(..))
345+-- >>> import Streamly.Data.Array (Array)
346+-- >>> import Streamly.Data.Fold (Fold)
343347-- >>> import Streamly.Data.Stream (Stream)
344348-- >>> import Data.IORef (newIORef, readIORef, writeIORef)
345349-- >>> import qualified Streamly.Data.Array as Array
@@ -379,33 +383,82 @@ drive strm fl = StreamD.fold fl $ StreamD.fromStreamK $ Stream.toStreamK strm
379383--
380384-- Definition:
381385--
382−-- >>> driveBreak = flip Stream.foldBreak
386+-- >>> breakStream = flip Stream.foldBreak
383387--
384388-- /CPS/
385389--
386−{-# INLINE driveBreak #-}
387−driveBreak :: Monad m => Stream m a -> Fold m a b -> m (b, Stream m a)
388−driveBreak strm fl = fmap f $ K.foldBreak fl (Stream.toStreamK strm)
390+{-# INLINE breakStream #-}
391+breakStream :: Monad m => Stream m a -> Fold m a b -> m (b, Stream m a)
392+breakStream strm fl = fmap f $ K.foldBreak fl (Stream.toStreamK strm)
389393
390394 where
391395
392396 f (b, str) = (b, Stream.fromStreamK str)
393397
394−-- | Augment a fold strictly by adding a stream to it.
398+-- | Append a stream to a fold to build the fold accumulator incrementally. We
399+-- can repeatedly call 'addStream' on the same fold to continue building the
400+-- fold and finally use 'drive' to finish the fold and extract the result. Also
401+-- see the 'Streamly.Data.Fold.addOne' operation which is a singleton version
402+-- of 'addStream'.
395403--
396404-- Definitions:
397405--
398−-- >>> augment stream = Fold.drive stream . Fold.duplicate
406+-- >>> addStream stream = Fold.drive stream . Fold.duplicate
407+--
408+-- Example, build a list incrementally:
409+--
410+-- >>> :{
411+-- pure (Fold.toList :: Fold IO Int [Int])
412+-- >>= Fold.addOne 1
413+-- >>= Fold.addStream (Stream.enumerateFromTo 2 4)
414+-- >>= Fold.drive Stream.nil
415+-- >>= print
416+-- :}
417+-- [1,2,3,4]
418+--
419+-- This can be used as an O(n) list append compared to the O(n^2) @++@ when
420+-- used for incrementally building a list.
421+--
422+-- Example, build a stream incrementally:
423+--
424+-- >>> :{
425+-- pure (Fold.toStream :: Fold IO Int (Stream Identity Int))
426+-- >>= Fold.addOne 1
427+-- >>= Fold.addStream (Stream.enumerateFromTo 2 4)
428+-- >>= Fold.drive Stream.nil
429+-- >>= print
430+-- :}
431+-- fromList [1,2,3,4]
432+--
433+-- This can be used as an O(n) stream append compared to the O(n^2) @<>@ when
434+-- used for incrementally building a stream.
435+--
436+-- Example, build an array incrementally:
437+--
438+-- >>> :{
439+-- pure (Array.write :: Fold IO Int (Array Int))
440+-- >>= Fold.addOne 1
441+-- >>= Fold.addStream (Stream.enumerateFromTo 2 4)
442+-- >>= Fold.drive Stream.nil
443+-- >>= print
444+-- :}
445+-- fromList [1,2,3,4]
446+--
447+-- Example, build an array stream incrementally:
399448--
400449-- >>> :{
401−-- Fold.augment (Stream.enumerateFromTo 1 10) Fold.sum
402−-- >>= Fold.augment (Stream.enumerateFromTo 11 20)
403−-- >>= Fold.drive (Stream.enumerateFromTo 21 30)
450+-- let f :: Fold IO Int (Stream Identity (Array Int))
451+-- f = Fold.chunksOf 2 (Array.writeN 3) Fold.toStream
452+-- in pure f
453+-- >>= Fold.addOne 1
454+-- >>= Fold.addStream (Stream.enumerateFromTo 2 4)
455+-- >>= Fold.drive Stream.nil
456+-- >>= print
404457-- :}
405−-- 465
458+-- fromList [fromList [1,2],fromList [3,4]]
406459--
407−augment :: Monad m => Stream m a -> Fold m a b -> m (Fold m a b)
408−augment stream = drive stream . duplicate
460+addStream :: Monad m => Stream m a -> Fold m a b -> m (Fold m a b)
461+addStream stream = drive stream . duplicate
409462
410463------------------------------------------------------------------------------
411464-- Transformations on fold inputs