85b69a7 · streamly · git.iko.soy

git.iko.soy/streamly

Edit/Update some docs on folds

commit85b69a7afa750ce22d9394b9c7654f74dab77dc9 authorHarendra Kumar <harendra@composewell.com> dateSun 7 Feb 2021, 19:30 (6 years ago) parent7de5d6d

4 files changed+49−1

compare with master

unifiedsplit

src/Streamly/Internal/Data/Fold/Types.hs+22 src/Streamly/Internal/Data/Parser.hs+1−1 src/Streamly/Internal/Data/Stream/IsStream/Common.hs+12 src/Streamly/Internal/Data/Stream/IsStream/Eliminate.hs+14

src/Streamly/Internal/Data/Fold/Types.hs+22

@@ -303,6 +303,9 @@ instance Functor (Step s) where

303303-- 'Step'). At any point the fold driver can extract the result from the

304304-- intermediate state using the @extract@ function.

305305--

306+-- NOTE: If you think you need the constructor of this type please consider

307+-- using the smart constructors in "Streamly.Internal.Data.Fold' instead.

308+--

306309-- @since 0.7.0

307310

308311data Fold m a b =

@@ -316,6 +319,9 @@ data Fold m a b =

316319-- | Make an accumulating (non-terminating) fold using a pure step function, a

317320-- pure initial state and a pure state extraction function.

318321--

322+-- If your 'Fold' returns only 'Partial' (i.e. never returns a 'Done') then you

323+-- can use @mkAccum*@ constructors.

324+--

319325-- /Internal/

320326--

321327{-# INLINE mkAccum #-}

@@ -329,6 +335,10 @@ mkAccum step initial extract =

329335-- | Similar to 'mkAccum' but the final state extracted is identical to the

330336-- intermediate state.

331337--

338+-- @

339+-- mkAccum_ step initial = mkAccum step initial id

340+-- @

341+--

332342-- /Internal/

333343--

334344{-# INLINE mkAccum_ #-}

@@ -348,6 +358,10 @@ mkAccumM step initial =

348358-- | Similar to 'mkAccumM' but the final state extracted is identical to the

349359-- intermediate state.

350360--

361+-- @

362+-- mkAccumM_ step initial = mkAccumM step initial return

363+-- @

364+--

351365-- /Internal/

352366--

353367{-# INLINE mkAccumM_ #-}

@@ -367,6 +381,10 @@ mkFold step initial extract =

367381-- | Similar to 'mkFold' but the final state extracted is identical to the

368382-- intermediate state.

369383--

384+-- @

385+-- mkFold_ step initial = mkFold step initial id

386+-- @

387+--

370388-- /Internal/

371389--

372390{-# INLINE mkFold_ #-}

@@ -389,6 +407,10 @@ mkFoldM = Fold

389407-- | Similar to 'mkFoldM' but the final state extracted is identical to the

390408-- intermediate state.

391409--

410+-- @

411+-- mkFoldM_ step initial = mkFoldM step initial return

412+-- @

413+--

392414-- /Internal/

393415--

394416{-# INLINE mkFoldM_ #-}

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

@@ -937,7 +937,7 @@ many f p = K.toParserK $ D.many f (K.fromParserK p)

937937-- Stops: when the downstream fold stops or the parser fails.

938938-- Fails: if it stops without producing a single result.

939939--

940−-- @some fld parser = many (takeGE 1 fld) parser@

940+-- @some fld parser = manyP (takeGE 1 fld) parser@

941941--

942942-- Compare with 'Control.Applicative.some'.

943943--

src/Streamly/Internal/Data/Stream/IsStream/Common.hs+12

@@ -223,6 +223,18 @@ relTimesWith = fmap snd . timesWith

223223-- >>> S.fold FL.sum (S.enumerateFromTo 1 100)

224224-- 5050

225225--

226+-- @fold f = parse (Parser.fromFold f)@

227+--

228+-- Folds can never fail, therefore, they always produce a default value even

229+-- when no input is provided. It means we can always fold an empty stream and

230+-- get a valid result. For example:

231+--

232+-- >>> Stream.fold Fold.sum Stream.nil

233+-- 0

234+--

235+-- However, 'foldMany' on an empty stream results in an empty stream.

236+-- Therefore, @fold f@ is not the same as @head . foldMany f@.

237+--

226238-- @since 0.7.0

227239{-# INLINE fold #-}

228240fold :: Monad m => Fold m a b -> SerialT m a -> m b

src/Streamly/Internal/Data/Stream/IsStream/Eliminate.hs+14

@@ -345,6 +345,20 @@ parseK = parse

345345

346346-- | Parse a stream using the supplied 'Parser'.

347347--

348+-- Unlike folds, parsers may not always result in a valid output, they may

349+-- result in an error. For example:

350+--

351+-- >>> Stream.parse (Parser.takeEQ 1 Fold.drain) Stream.nil

352+-- *** Exception: ParseError "takeEQ: Expecting exactly 1 elements, input terminated on 0"

353+--

354+-- Note:

355+--

356+-- @

357+-- fold f = parse (Parser.fromFold f)

358+-- @

359+--

360+-- @parse p@ is not the same as @head . parseMany p@ on an empty stream.

361+--

348362-- /Internal/

349363--

350364{-# INLINE [3] parse #-}