@@ -689,6 +689,7 @@ module Streamly.Prelude
689 -- $application
689 -- $application
693 -- ** Concurrency Control
694 -- ** Concurrency Control
694 -- $concurrency
695 -- $concurrency
@@ -703,99 +704,34 @@ module Streamly.Prelude
703 , maxRate
704 , maxRate
704 , constRate
705 , constRate
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.
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.
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.
733− -- -- ** Splitting By Elements
738− , wordsBy -- strip, compact and split
741− -- | Splitting a stream by combining multiple contiguous elements into
742− -- groups using some criterion.
747 -- * Combining Streams
707 -- * Combining Streams
748 -- | New streams can be constructed by appending, merging or zipping
708 -- | New streams can be constructed by appending, merging or zipping
749 -- existing streams.
709 -- existing streams.
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.
758− -- -------Stream m a------|-------Stream m a------|=>----Stream m a---
763− -- >> S.toList $ S.fromList [1,2] \<> S.fromList [3,4]
765− -- >> S.toList $ fold $ [S.fromList [1,2], S.fromList [3,4]]
773− -- ** Concurrent Scheduling
774− -- | Any exceptions generated by concurrent evaluation are propagated to
711+ -- Any exceptions generated by concurrent evaluation are propagated to
775 -- the consumer of the stream as soon as they occur. Exceptions from a
712 -- the consumer of the stream as soon as they occur. Exceptions from a
776 -- particular stream are guaranteed to arrive in the same order in the
713 -- particular stream are guaranteed to arrive in the same order in the
777 -- output stream as they were generated in the input stream.
714 -- output stream as they were generated in the input stream.
779− -- See 'maxThreads' and 'maxBuffer' to control the concurrency of these
716+ -- See 'maxThreads' and 'maxBuffer' to control the concurrency of the
717+ -- concurrent combinators.
780− -- combinators.
719+ -- ** Linear combinators
720+ -- | These functions have O(n) append performance. They can be used
721+ -- efficiently with 'concatMapWith' et. al.
784 , parallel
728 , parallel
787− -- ** Merging
730+ -- ** PairWise combinators
788− -- | Streams form a commutative semigroup under the merge
731+ -- | These functions have O(n^2) append performance when used linearly e.g.
789− -- operation. Merging can be considered as a generalization of inserting an
732+ -- using 'concatMapWith'. However, they can be combined pair wise using
790− -- element in a stream to interleaving a stream with another stream.
733+ -- 'Streamly.Internal.Data.Stream.IsStream.Expand.concatPairsWith' to give
791− --
734+ -- O(n * log n) complexity.
794− -- -------Stream m a------|
795− -- |=>----Stream m a---
796− -- -------Stream m a------|
800 -- , merge
736 -- , merge
801 , mergeBy
737 , mergeBy
@@ -803,21 +739,15 @@ module Streamly.Prelude
803 , mergeAsyncBy
739 , mergeAsyncBy
804 , mergeAsyncByM
740 , mergeAsyncByM
810− -- -------Stream m a------|
811− -- |=>----Stream m c---
812− -- -------Stream m b------|
815 , zipWith
742 , zipWith
816 , zipWithM
743 , zipWithM
817 , zipAsyncWith
744 , zipAsyncWith
818 , zipAsyncWithM
745 , zipAsyncWithM
820− -- ** Folding Streams of Streams
747+ -- ** Nested Unfolds
750+ -- ** Nested Streams
821 -- | Stream operations like map and filter represent loop processing in
751 -- | Stream operations like map and filter represent loop processing in
822 -- imperative programming terms. Similarly, the imperative concept of
752 -- imperative programming terms. Similarly, the imperative concept of
823 -- nested loops are represented by streams of streams. The 'concatMap'
753 -- nested loops are represented by streams of streams. The 'concatMap'
@@ -844,9 +774,8 @@ module Streamly.Prelude
844 , concatMapWith
774 , concatMapWith
845 , concatMap
775 , concatMap
846 , concatMapM
776 , concatMapM
849− -- ** Folding Containers of Streams
778+ -- ** Containers of Streams
850 -- | These are variants of standard 'Foldable' fold functions that use a
779 -- | These are variants of standard 'Foldable' fold functions that use a
851 -- polymorphic stream sum operation (e.g. 'async' or 'wSerial') to fold a
780 -- polymorphic stream sum operation (e.g. 'async' or 'wSerial') to fold a
852 -- finite container of streams. Note that these are just special cases of
781 -- finite container of streams. Note that these are just special cases of
@@ -856,6 +785,47 @@ module Streamly.Prelude
856 , concatMapFoldableWith
785 , concatMapFoldableWith
857 , concatForFoldableWith
786 , concatForFoldableWith
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.
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.
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.
815+ -- -- ** Splitting By Elements
820+ , wordsBy -- strip, compact and split
823+ -- | Splitting a stream by combining multiple contiguous elements into
824+ -- groups using some criterion.
859 -- * Exceptions
829 -- * Exceptions
860 -- | Most of these combinators inhibit stream fusion, therefore, when
830 -- | Most of these combinators inhibit stream fusion, therefore, when
861 -- possible, they should be called in an outer loop to mitigate the cost.
831 -- possible, they should be called in an outer loop to mitigate the cost.