85b69a7 · streamly · git.iko.soy

git.iko.soy/streamly

on master help sign in

Edit/Update some docs on folds

85b69a7Harendra Kumar6 years ago

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

compare with master

unifiedsplit

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

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

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

305--

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+--

306-- @since 0.7.0

309-- @since 0.7.0

307

310

308data Fold m a b =

311data Fold m a b =

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

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

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

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

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

318--

321--

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

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

324+--

319-- /Internal/

325-- /Internal/

320--

326--

321{-# INLINE mkAccum #-}

327{-# INLINE mkAccum #-}

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

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

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

330-- intermediate state.

336-- intermediate state.

331--

337--

338+-- @

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

340+-- @

341+--

332-- /Internal/

342-- /Internal/

333--

343--

334{-# INLINE mkAccum_ #-}

344{-# INLINE mkAccum_ #-}

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

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

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

349-- intermediate state.

359-- intermediate state.

350--

360--

361+-- @

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

363+-- @

364+--

351-- /Internal/

365-- /Internal/

352--

366--

353{-# INLINE mkAccumM_ #-}

367{-# INLINE mkAccumM_ #-}

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

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

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

368-- intermediate state.

382-- intermediate state.

369--

383--

384+-- @

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

386+-- @

387+--

370-- /Internal/

388-- /Internal/

371--

389--

372{-# INLINE mkFold_ #-}

390{-# INLINE mkFold_ #-}

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

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

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

390-- intermediate state.

408-- intermediate state.

391--

409--

410+-- @

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

412+-- @

413+--

392-- /Internal/

414-- /Internal/

393--

415--

394{-# INLINE mkFoldM_ #-}

416{-# 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)

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

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

939--

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

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

941--

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

943--

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

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

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

224-- 5050

225--

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+--

226-- @since 0.7.0

238-- @since 0.7.0

227{-# INLINE fold #-}

239{-# INLINE fold #-}

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

240fold :: 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

345

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

347--

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+--

348-- /Internal/

362-- /Internal/

349--

363--

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

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