1889b4e · streamly · git.iko.soy

git.iko.soy/streamly

update fold documentation

commit1889b4eef686afc1e9b9a9f69f80b659bd5dc5c7 authorHarendra Kumar <harendra@composewell.com> dateThu 23 Apr 2020, 10:38 (6 years ago) parent684d278

3 files changed+28−12

compare with master

unifiedsplit

src/Streamly/Internal/Data/Fold.hs+1−1 src/Streamly/Internal/Prelude.hs+2−2 src/Streamly/Prelude.hs+25−9

src/Streamly/Internal/Data/Fold.hs+1−1

@@ -744,7 +744,7 @@ head = _Fold1 const

744744--

745745-- @

746746-- find p = fmap getFirst $

747−-- foldMap (\x -> First (if p x then Just x else Nothing))

747+-- FL.foldMap (\x -> First (if p x then Just x else Nothing))

748748-- @

749749--

750750-- @since 0.7.0

src/Streamly/Internal/Prelude.hs+2−2

@@ -3196,9 +3196,9 @@ splitParseTill = undefined

31963196--

31973197-- | Iterate a parser generating function on a stream. The initial value @b@ is

31983198-- used to generate the first parser, the parser is applied on the stream and

3199−-- the result is used generate the next parser and so on.

3199+-- the result is used to generate the next parser and so on.

32003200--

3201−-- >>> S.toList $ S.concatParse (\b -> PR.take 2 (FL.mconcatTo b)) 0 $ S.fromList [1..10]

3201+-- >>> S.toList $ S.map getSum $ S.concatParse (\b -> PR.take 2 (FL.mconcatTo b)) 0 $ S.map Sum $ S.fromList [1..10]

32023202-- > [3,10,21,36,55,55]

32033203--

32043204-- This is the streaming equivalent of monad like sequenced application of

src/Streamly/Prelude.hs+25−9

@@ -120,15 +120,31 @@ module Streamly.Prelude

120120 -- ** Folding

121121-- | In imperative terms a fold can be considered as a loop over the stream

122122-- that reduces the stream to a single value.

123−-- Left and right folds use a fold function @f@ and an identity element @z@

124−-- (@zero@) to recursively deconstruct a structure and then combine and reduce

125−-- the values or transform and reconstruct a new container.

126−--

127−-- In general, a right fold is suitable for transforming and reconstructing a

128−-- right associated structure (e.g. cons lists and streamly streams) and a left

129−-- fold is suitable for reducing a right associated structure. The behavior of

130−-- right and left folds are described in detail in the individual fold's

131−-- documentation. To illustrate the two folds for cons lists:

123+-- Left and right folds both use a fold function @f@ and an identity element

124+-- @z@ (@zero@) to deconstruct a recursive data structure and reconstruct a

125+-- new data structure. The new structure may be a recursive construction (a

126+-- container) or a non-recursive single value reduction of the original

127+-- structure.

128+--

129+-- Both right and left folds are mathematical duals of each other, they are

130+-- functionally equivalent. Operationally, a left fold on a left associated

131+-- structure behaves exactly in the same way as a right fold on a right

132+-- associated structure. Similarly, a left fold on a right associated structure

133+-- behaves in the same way as a right fold on a left associated structure.

134+-- However, the behavior of a right fold on a right associated structure is

135+-- operationally different (even though functionally equivalent) than a left

136+-- fold on the same structure.

137+--

138+-- On right associated structures like Haskell @cons@ lists or Streamly

139+-- streams, a lazy right fold is naturally suitable for lazy recursive

140+-- reconstruction of a new structure, while a strict left fold is naturally

141+-- suitable for efficient reduction. In right folds control is in the hand of

142+-- the @puller@ whereas in left folds the control is in the hand of the

143+-- @pusher@.

144+--

145+-- The behavior of right and left folds are described in detail in the

146+-- individual fold's documentation. To illustrate the two folds for right

147+-- associated @cons@ lists:

132148--

133149-- > foldr :: (a -> b -> b) -> b -> [a] -> b

134150-- > foldr f z [] = z