@@ -232,7 +232,7 @@ module Streamly.Internal.Data.Fold.Type
232232 , take
233233
234234 -- ** Serial Append
235− , serialWith
235+ , serialWith -- rename to "append"
236236 , serial_
237237
238238 -- ** Parallel Distribution
@@ -253,10 +253,11 @@ module Streamly.Internal.Data.Fold.Type
253253 -- ** Nesting
254254 , concatMap
255255
256− -- * Running Partially
257− , duplicate
256+ -- * Running A Fold
258257 , initialize
259− , runStep
258+ , snoc
259+ , duplicate
260+ , finish
260261
261262 -- * Fold2
262263 , Fold2 (..)
@@ -1149,20 +1150,29 @@ take n (Fold fstep finitial fextract) = Fold step initial extract
11491150-- Nesting
11501151------------------------------------------------------------------------------
11511152
1152−-- | Modify the fold such that it returns a new 'Fold' instead of the output.
1153−-- If the fold was already done the returned fold would always yield the
1154−-- result. If the fold was partial, the returned fold starts from where we left
1155−-- i.e. it uses the last accumulator value as the initial value of the
1156−-- accumulator. Thus we can resume the fold later and feed it more input.
1153+-- | 'duplicate' provides the ability to run a fold in parts. The duplicated
1154+-- fold consumes the input and returns the same fold as output instead of
1155+-- returning the final result, the returned fold can be run later to consume
1156+-- more input.
1157+--
1158+-- We can append a stream to a fold as follows:
1159+--
1160+-- >>> :{
1161+-- foldAppend :: Monad m => Fold m a b -> SerialT m a -> m (Fold m a b)
1162+-- foldAppend f = Stream.fold (Fold.duplicate f)
1163+-- :}
11571164--
11581165-- >>> :{
11591166-- do
1160−-- more <- Stream.fold (Fold.duplicate Fold.sum) (Stream.enumerateFromTo 1 10)
1161−-- evenMore <- Stream.fold (Fold.duplicate more) (Stream.enumerateFromTo 11 20)
1162−-- Stream.fold evenMore (Stream.enumerateFromTo 21 30)
1167+-- sum1 <- foldAppend Fold.sum (Stream.enumerateFromTo 1 10)
1168+-- sum2 <- foldAppend sum1 (Stream.enumerateFromTo 11 20)
1169+-- Stream.fold sum2 (Stream.enumerateFromTo 21 30)
11631170-- :}
11641171-- 465
11651172--
1173+-- 'duplicate' essentially appends a stream to the fold without finishing the
1174+-- fold. Compare with 'snoc' which appends a singleton value to the fold.
1175+--
11661176-- /Pre-release/
11671177{-# INLINABLE duplicate #-}
11681178duplicate :: Monad m => Fold m a b -> Fold m a (Fold m a b)
@@ -1185,19 +1195,38 @@ initialize (Fold step initial extract) = do
11851195 i <- initial
11861196 return $ Fold step (return i) extract
11871197
1188−-- | Run one step of a fold and store the accumulator as an initial value in
1189−-- the returned fold.
1198+-- | Append a singleton value to the fold.
1199+--
1200+-- >>> import qualified Data.Foldable as Foldable
1201+-- >>> Foldable.foldlM Fold.snoc Fold.toList [1..3] >>= Fold.finish
1202+-- [1,2,3]
1203+--
1204+-- Compare with 'duplicate' which allows appending a stream to the fold.
11901205--
11911206-- /Pre-release/
1192−{-# INLINE runStep #-}
1193−runStep :: Monad m => Fold m a b -> a -> m (Fold m a b)
1194−runStep (Fold step initial extract) a = do
1207+{-# INLINE snoc #-}
1208+snoc :: Monad m => Fold m a b -> a -> m (Fold m a b)
1209+snoc (Fold step initial extract) a = do
11951210 res <- initial
11961211 r <- case res of
11971212 Partial fs -> step fs a
1198− b@(Done _) -> return b
1213+ Done _ -> return res
11991214 return $ Fold step (return r) extract
12001215
1216+-- | Finish the fold to extract the current value of the fold.
1217+--
1218+-- >>> Fold.finish Fold.toList
1219+-- []
1220+--
1221+-- /Pre-release/
1222+{-# INLINE finish #-}
1223+finish :: Monad m => Fold m a b -> m b
1224+finish (Fold _ initial extract) = do
1225+ res <- initial
1226+ case res of
1227+ Partial fs -> extract fs
1228+ Done b -> return b
1229+
12011230------------------------------------------------------------------------------
12021231-- Parsing
12031232------------------------------------------------------------------------------