@@ -76,10 +76,13 @@ module Streamly.Fold
7676 , foldMapM
7777
7878 -- ** Full Folds (To Containers)
79− -- , toStream -- experimental
79+ -- | Avoid using these folds in scalable or performance critical
80+ -- applications, they buffer all the input in memory.
81+
82+ , toStream -- experimental
8083 , toStreamRev -- experimental
8184
82− -- , toList
85+ , toList
8386 , toListRev -- experimental
8487
8588 -- ** Partial Folds
@@ -646,9 +649,9 @@ foldMapM act = Fold step begin done
646649-- @since 0.7.0
647650
648651-- id . (x1 :) . (x2 :) . (x3 :) . ... . (xn :) $ []
649−{-# INLINABLE _toList #-}
650−_toList :: Monad m => Fold m a [a]
651−_toList = Fold (\f x -> return $ f . (x :))
652+{-# INLINABLE toList #-}
653+toList :: Monad m => Fold m a [a]
654+toList = Fold (\f x -> return $ f . (x :))
652655 (return id)
653656 (return . ($ []))
654657
@@ -673,9 +676,9 @@ toListRev = Fold (\xs x -> return $ x:xs) (return []) return
673676-- be very inefficient, consider using "Streamly.Array" instead.
674677--
675678-- @since 0.7.0
676−{-# INLINABLE _toStream #-}
677−_toStream :: Monad m => Fold m a (SerialT Identity a)
678−_toStream = Fold (\f x -> return $ f . (x `K.cons`))
679+{-# INLINABLE toStream #-}
680+toStream :: Monad m => Fold m a (SerialT Identity a)
681+toStream = Fold (\f x -> return $ f . (x `K.cons`))
679682 (return id)
680683 (return . ($ K.nil))
681684
@@ -943,13 +946,31 @@ ltakeWhile predicate (Fold step initial done) = Fold step' initial' done'
943946------------------------------------------------------------------------------
944947--
945948
946−{-
947−-- | Split the input stream into two groups at index @n@, the first group
948−-- consisting of elements from index @0@ to index @n - 1@ i.e. the stream
949−-- prefix of length @n@ and the second group consisting of the rest of the
950−-- stream.
949+-- | @splitAt n f1 f2@ composes folds @f1@ and @f2@ such that first @n@
950+-- elements of its input are sent to fold @f1@ and the rest of the stream is
951+-- sent to fold @f2@.
951952--
952−-}
953+-- > let splitAt_ n xs = FL.foldl' (FL.splitAt n FL.toList FL.toList) $ S.fromList xs
954+--
955+-- >>> splitAt_ 6 "Hello World!"
956+-- > ("Hello ","World!")
957+--
958+-- >>> splitAt_ (-1) [1,2,3]
959+-- > ([],[1,2,3])
960+--
961+-- >>> splitAt_ 0 [1,2,3]
962+-- > ([],[1,2,3])
963+--
964+-- >>> splitAt_ 1 [1,2,3]
965+-- > ([1],[2,3])
966+--
967+-- >>> splitAt_ 3 [1,2,3]
968+-- > ([1,2,3],[])
969+--
970+-- >>> splitAt_ 4 [1,2,3]
971+-- > ([1,2,3],[])
972+--
973+-- @since 0.7.0
953974{-# INLINE splitAt #-}
954975splitAt
955976 :: Monad m
@@ -1018,11 +1039,11 @@ intervalsOf n f m = grouped (lcatMaybes f) s
10181039-- Binary APIs
10191040------------------------------------------------------------------------------
10201041
1042+{-
10211043-- | Break the input stream into two groups, the first group takes the input as
10221044-- long as the predicate applied to the first element of the stream and next
10231045-- input element holds 'True', the second group takes the rest of the input.
10241046--
1025−{-
10261047spanBy
10271048 :: Monad m
10281049 => (a -> a -> Bool)
@@ -1052,11 +1073,23 @@ spanBy cmp (Fold stepL initialL extractL) (Fold stepR initialR extractR) =
10521073 extract (Tuple3' a b _) = (,) <$> extractL a <*> extractR b
10531074-}
10541075
1055−-- |
1076+-- | Span as long as the predicate is 'True'. @span p f1 f2@ composes folds
1077+-- @f1@ and @f2@ such that the composed fold continues sending the input to
1078+-- @f1@ as long as the predicate @p@ is 'True'. The rest of the input is sent
1079+-- to @f2@.
10561080--
1057−-- Break the input stream into two groups, the first group takes the input as
1058−-- long as the predicate is 'True', the second group takes the rest of the
1059−-- input.
1081+-- > let span_ p xs = FL.foldl' (FL.span p FL.toList FL.toList) $ S.fromList xs
1082+--
1083+-- >>> span_ (< 1) [1,2,3]
1084+-- > ([],[1,2,3])
1085+--
1086+-- >>> span_ (< 2) [1,2,3]
1087+-- > ([1],[2,3])
1088+--
1089+-- >>> span_ (< 4) [1,2,3]
1090+-- > ([1,2,3],[])
1091+--
1092+-- @since 0.7.0
10601093{-# INLINE span #-}
10611094span
10621095 :: Monad m
@@ -1080,9 +1113,22 @@ span p (Fold stepL initialL extractL) (Fold stepR initialR extractR) =
10801113-- |
10811114-- > break p = span (not . p)
10821115--
1083−-- Break the input stream into two groups, the first group takes the input as
1084−-- long as the predicate is 'False', the second group takes the rest of the
1085−-- input.
1116+-- Break as soon as the predicate becomes 'True'. @break p f1 f2@ composes
1117+-- folds @f1@ and @f2@ such that @f1@ stops receiving input as soon as the
1118+-- predicate @p@ becomes 'True'. The rest of the input is sent to @f2@.
1119+--
1120+-- > let break_ p xs = FL.foldl' (FL.break p FL.toList FL.toList) $ S.fromList xs
1121+--
1122+-- >>> break_ (< 1) [3,2,1]
1123+-- > ([3,2,1],[])
1124+--
1125+-- >>> break_ (< 2) [3,2,1]
1126+-- > ([3,2],[1])
1127+--
1128+-- >>> break_ (< 4) [3,2,1]
1129+-- > ([],[3,2,1])
1130+--
1131+-- @since 0.7.0
10861132{-# INLINE break #-}
10871133break
10881134 :: Monad m
@@ -1144,13 +1190,14 @@ _newline m = S.foldrS (\x xs ->
11441190 then (x,True) `K.cons` xs
11451191 else (x,False) `K.cons` xs) K.nil m
11461192
1147−-- | Group by applying a predicate to the first element of the current group
1148−-- and the next element in the input stream. The next element is considered
1149−-- part of the current group if the predicate succeeds otherwise a new group
1150−-- starts.
1193+-- | @groupsBy cmp f $ S.fromList [a,b,c,...]@ assigns the element @a@ to the
1194+-- first group, if @a \`cmp` b@ is 'True' then @b@ is also assigned to the same
1195+-- group. If @a \`cmp` c@ is 'True' then @c@ is also assigned to the same
1196+-- group and so on. When the comparison fails a new group is started. Each
1197+-- group is folded using the fold @f@.
11511198--
1152−-- >>> S.toList $ FL.groupsBy (==) FL.toList $ S.fromList [1,1,2,2]
1153−-- > [[1,1],[2,2]]
1199+-- >>> S.toList $ FL.groupsBy (>) FL.toList $ S.fromList [1,3,7,0,2,5]
1200+-- > [[1,3,7],[0,2,5]]
11541201--
11551202-- @since 0.7.0
11561203groupsBy
@@ -1161,13 +1208,18 @@ groupsBy
11611208 -> t m b
11621209groupsBy cmp f m = D.fromStreamD $ D.groupsBy cmp f (D.toStreamD m)
11631210
1164−{-
1165−-- | Apply a predicate to each new element in the input stream and the last
1166−-- element of the current group. In other words, perform a rolling comparison
1167−-- between two successive elements in the stream. The new element is considered
1168−-- part of the current group if the predicate succeeds otherwise a new group
1169−-- starts.
1170−-}
1211+-- | Unlike @groupsBy@ this function performs a rolling comparison of two
1212+-- successive elements in the input stream. @groupsRollingBy cmp f $ S.fromList
1213+-- [a,b,c,...]@ assigns the element @a@ to the first group, if @a \`cmp` b@ is
1214+-- 'True' then @b@ is also assigned to the same group. If @b \`cmp` c@ is
1215+-- 'True' then @c@ is also assigned to the same group and so on. When the
1216+-- comparison fails a new group is started. Each group is folded using the fold
1217+-- @f@.
1218+--
1219+-- >>> S.toList $ FL.groupsRollingBy (\a b -> a + 1 == b) FL.toList $ S.fromList [1,2,3,7,8,9]
1220+-- > [[1,2,3],[7,8,9]]
1221+--
1222+-- @since 0.7.0
11711223groupsRollingBy
11721224 :: (IsStream t, Monad m)
11731225 => (a -> a -> Bool)
@@ -1178,6 +1230,9 @@ groupsRollingBy cmp f m = D.fromStreamD $ D.groupsRollingBy cmp f (D.toStreamD
11781230
11791231-- |
11801232-- > groups = groupsBy (==)
1233+-- > groups = groupsRollingBy (==)
1234+--
1235+-- Groups a contiguous span of equal elements together in one group.
11811236--
11821237-- >>> S.toList $ FL.groups FL.toList $ S.fromList [1,1,2,2]
11831238-- > [[1,1],[2,2]]