@@ -689,6 +689,7 @@ module Streamly.Prelude
689689 -- $application
690690 , (|$)
691691 , (|&)
692+ , mkAsync
692693
693694 -- ** Concurrency Control
694695 -- $concurrency
@@ -703,99 +704,34 @@ module Streamly.Prelude
703704 , maxRate
704705 , constRate
705706
706− -- * Splitting
707− -- | In general we can express splitting in terms of parser combinators.
708− -- These are some common use functions for convenience and efficiency.
709− -- While parsers can fail these functions are designed to transform a
710− -- stream without failure with a predefined behavior for all cases.
711− --
712− -- In general, there are three possible ways of combining stream segments
713− -- with a separator. The separator could be prefixed to each segment,
714− -- suffixed to each segment, or it could be infixed between segments.
715− -- 'intersperse' and 'intercalate' operations are examples of infixed
716− -- combining whereas 'unlines' is an example of suffixed combining. When we
717− -- split a stream with separators we can split in three different ways,
718− -- each being an opposite of the three ways of combining.
719− --
720− -- Splitting may keep the separator or drop it. Depending on how we split,
721− -- the separator may be kept attached to the stream segments in prefix or
722− -- suffix position or as a separate element in infix position. Combinators
723− -- like 'splitOn' that use @On@ in their names drop the separator and
724− -- combinators that use 'With' in their names keep the separator. When a
725− -- segment is missing it is considered as empty, therefore, we never
726− -- encounter an error in parsing.
727−
728− -- -- ** Breaking
729−
730− , chunksOf
731− , intervalsOf
732−
733− -- -- ** Splitting By Elements
734− , splitOn
735− , splitOnSuffix
736−
737− , splitWithSuffix
738− , wordsBy -- strip, compact and split
739−
740− -- ** Grouping
741− -- | Splitting a stream by combining multiple contiguous elements into
742− -- groups using some criterion.
743− , groups
744− , groupsBy
745− , groupsByRolling
746−
747707 -- * Combining Streams
748708 -- | New streams can be constructed by appending, merging or zipping
749709 -- existing streams.
750−
751− -- ** Appending
752− -- | Streams form a 'Semigroup' and a 'Monoid' under the append
753− -- operation. Appending can be considered as a generalization of the `cons`
754− -- operation to consing a stream to a stream.
755− --
756− -- @
757− --
758− -- -------Stream m a------|-------Stream m a------|=>----Stream m a---
759710 --
760− -- @
761− --
762− -- @
763− -- >> S.toList $ S.fromList [1,2] \<> S.fromList [3,4]
764− -- [1,2,3,4]
765− -- >> S.toList $ fold $ [S.fromList [1,2], S.fromList [3,4]]
766− -- [1,2,3,4]
767− -- @
768− , serial
769−
770− -- ** Interleaving
771− , wSerial
772−
773− -- ** Concurrent Scheduling
774− -- | Any exceptions generated by concurrent evaluation are propagated to
711+ -- Any exceptions generated by concurrent evaluation are propagated to
775712 -- the consumer of the stream as soon as they occur. Exceptions from a
776713 -- particular stream are guaranteed to arrive in the same order in the
777714 -- output stream as they were generated in the input stream.
778715 --
779− -- See 'maxThreads' and 'maxBuffer' to control the concurrency of these
780− -- combinators.
716+ -- See 'maxThreads' and 'maxBuffer' to control the concurrency of the
717+ -- concurrent combinators.
718+
719+ -- ** Linear combinators
720+ -- | These functions have O(n) append performance. They can be used
721+ -- efficiently with 'concatMapWith' et. al.
722+
723+ , serial
724+ , wSerial
781725 , ahead
782726 , async
783727 , wAsync
784728 , parallel
785− , mkAsync
786729
787− -- ** Merging
788− -- | Streams form a commutative semigroup under the merge
789− -- operation. Merging can be considered as a generalization of inserting an
790− -- element in a stream to interleaving a stream with another stream.
791− --
792− -- @
793− --
794− -- -------Stream m a------|
795− -- |=>----Stream m a---
796− -- -------Stream m a------|
797− -- @
798− --
730+ -- ** PairWise combinators
731+ -- | These functions have O(n^2) append performance when used linearly e.g.
732+ -- using 'concatMapWith'. However, they can be combined pair wise using
733+ -- 'Streamly.Internal.Data.Stream.IsStream.Expand.concatPairsWith' to give
734+ -- O(n * log n) complexity.
799735
800736 -- , merge
801737 , mergeBy
@@ -803,21 +739,15 @@ module Streamly.Prelude
803739 , mergeAsyncBy
804740 , mergeAsyncByM
805741
806− -- ** Zipping
807− -- |
808− -- @
809− --
810− -- -------Stream m a------|
811− -- |=>----Stream m c---
812− -- -------Stream m b------|
813− -- @
814− --
815742 , zipWith
816743 , zipWithM
817744 , zipAsyncWith
818745 , zipAsyncWithM
819746
820− -- ** Folding Streams of Streams
747+ -- ** Nested Unfolds
748+ , unfoldMany
749+
750+ -- ** Nested Streams
821751 -- | Stream operations like map and filter represent loop processing in
822752 -- imperative programming terms. Similarly, the imperative concept of
823753 -- nested loops are represented by streams of streams. The 'concatMap'
@@ -844,9 +774,8 @@ module Streamly.Prelude
844774 , concatMapWith
845775 , concatMap
846776 , concatMapM
847− , unfoldMany
848777
849− -- ** Folding Containers of Streams
778+ -- ** Containers of Streams
850779 -- | These are variants of standard 'Foldable' fold functions that use a
851780 -- polymorphic stream sum operation (e.g. 'async' or 'wSerial') to fold a
852781 -- finite container of streams. Note that these are just special cases of
@@ -856,6 +785,47 @@ module Streamly.Prelude
856785 , concatMapFoldableWith
857786 , concatForFoldableWith
858787
788+ -- * Splitting
789+ -- | In general we can express splitting in terms of parser combinators.
790+ -- These are some common use functions for convenience and efficiency.
791+ -- While parsers can fail these functions are designed to transform a
792+ -- stream without failure with a predefined behavior for all cases.
793+ --
794+ -- In general, there are three possible ways of combining stream segments
795+ -- with a separator. The separator could be prefixed to each segment,
796+ -- suffixed to each segment, or it could be infixed between segments.
797+ -- 'intersperse' and 'intercalate' operations are examples of infixed
798+ -- combining whereas 'unlines' is an example of suffixed combining. When we
799+ -- split a stream with separators we can split in three different ways,
800+ -- each being an opposite of the three ways of combining.
801+ --
802+ -- Splitting may keep the separator or drop it. Depending on how we split,
803+ -- the separator may be kept attached to the stream segments in prefix or
804+ -- suffix position or as a separate element in infix position. Combinators
805+ -- like 'splitOn' that use @On@ in their names drop the separator and
806+ -- combinators that use 'With' in their names keep the separator. When a
807+ -- segment is missing it is considered as empty, therefore, we never
808+ -- encounter an error in parsing.
809+
810+ -- -- ** Breaking
811+
812+ , chunksOf
813+ , intervalsOf
814+
815+ -- -- ** Splitting By Elements
816+ , splitOn
817+ , splitOnSuffix
818+
819+ , splitWithSuffix
820+ , wordsBy -- strip, compact and split
821+
822+ -- ** Grouping
823+ -- | Splitting a stream by combining multiple contiguous elements into
824+ -- groups using some criterion.
825+ , groups
826+ , groupsBy
827+ , groupsByRolling
828+
859829 -- * Exceptions
860830 -- | Most of these combinators inhibit stream fusion, therefore, when
861831 -- possible, they should be called in an outer loop to mitigate the cost.