@@ -677,7 +677,16 @@ foldl' fstep begin = foldlM' (\b a -> return (fstep b a)) (return begin)
677677-- Special folds
678678------------------------------------------------------------------------------
679679
680−-- | Run a streaming composition, discard the results.
680+-- >>> drain = mapM_ (\_ -> return ())
681+
682+-- |
683+-- Definitions:
684+--
685+-- >>> drain = Stream.fold Fold.drain
686+-- >>> drain = Stream.foldrM (\_ xs -> xs) (return ())
687+--
688+-- Run a stream, discarding the results.
689+--
681690{-# INLINE_LATE drain #-}
682691drain :: Monad m => Stream m a -> m ()
683692-- drain = foldrM (\_ xs -> xs) (return ())
@@ -694,6 +703,45 @@ drain (Stream step state) = go SPEC state
694703-- To Containers
695704------------------------------------------------------------------------------
696705
706+-- This toList impl is faster (30% on streaming-benchmarks) than the
707+-- corresponding left fold. The left fold retains an additional argument in the
708+-- recursive loop.
709+--
710+-- Core for the right fold loop:
711+--
712+-- main_$s$wgo1
713+-- = \ sc_s3e6 sc1_s3e5 ->
714+-- case ># sc1_s3e5 100000# of {
715+-- __DEFAULT ->
716+-- case main_$s$wgo1 sc_s3e6 (+# sc1_s3e5 1#) of
717+--
718+-- Core for the left fold loop:
719+--
720+-- main_$s$wgo1
721+-- = \ sc_s3oT sc1_s3oS sc2_s3oR ->
722+-- case sc2_s3oR of fs2_a2lw { __DEFAULT ->
723+-- case ># sc1_s3oS 100000# of {
724+-- __DEFAULT ->
725+-- let { wild_a2og = I# sc1_s3oS } in
726+-- main_$s$wgo1
727+-- sc_s3oT (+# sc1_s3oS 1#) (\ x_X9 -> fs2_a2lw (: wild_a2og x_X9));
728+
729+-- |
730+-- Definitions:
731+--
732+-- >>> toList = Stream.foldr (:) []
733+-- >>> toList = Stream.fold Fold.toList
734+--
735+-- Convert a stream into a list in the underlying monad. The list can be
736+-- consumed lazily in a lazy monad (e.g. 'Identity'). In a strict monad (e.g.
737+-- IO) the whole list is generated and buffered before it can be consumed.
738+--
739+-- /Warning!/ working on large lists accumulated as buffers in memory could be
740+-- very inefficient, consider using "Streamly.Data.Array" instead.
741+--
742+-- Note that this could a bit more efficient compared to @Stream.fold
743+-- Fold.toList@, and it can fuse with pure list consumers.
744+--
697745{-# INLINE_NORMAL toList #-}
698746toList :: Monad m => Stream m a -> m [a]
699747toList = Streamly.Internal.Data.Stream.StreamD.Type.foldr (:) []