9541caf · streamly · git.iko.soy

git.iko.soy/streamly

Add the upgrade guide examples to haddock

commit9541caf7af21266da01286f6150bb8c114b87e80 authorHarendra Kumar <harendra@composewell.com> dateFri 17 Mar 2023, 03:16 (4 years ago) parent02eba55

4 files changed+50−6

compare with master

unifiedsplit

core/src/DocTestDataStream.hs+1 core/src/Streamly/Data/Stream.hs+31−5 core/src/Streamly/Data/StreamK.hs+6 src/Streamly/Internal/Data/Stream/Concurrent.hs+12−1

core/src/DocTestDataStream.hs+1

@@ -22,6 +22,7 @@

2222>>> import qualified Streamly.Data.Array as Array

2323>>> import qualified Streamly.Data.Fold as Fold

2424>>> import qualified Streamly.Data.Stream as Stream

25+>>> import qualified Streamly.Data.StreamK as StreamK

2526>>> import qualified Streamly.Data.Unfold as Unfold

2627>>> import qualified Streamly.Data.Parser as Parser

2728>>> import qualified Streamly.FileSystem.Dir as Dir

core/src/Streamly/Data/Stream.hs+31−5

@@ -39,6 +39,14 @@ module Streamly.Data.Stream

3939 --

4040 -- See also: "Streamly.Internal.Data.Stream.Generate" for

4141 -- @Pre-release@ functions.

42+ --

43+ -- Useful Idioms:

44+ --

45+ -- >>> fromIndices f = fmap f $ Stream.enumerateFrom 0

46+ -- >>> fromIndicesM f = Stream.mapM f $ Stream.enumerateFrom 0

47+ -- >>> fromListM = Stream.sequence . Stream.fromList

48+ -- >>> fromFoldable = StreamK.toStream . StreamK.fromFoldable

49+ -- >>> fromFoldableM = Stream.sequence . fromFoldable

4250

4351 -- ** Primitives

4452 -- | Primitives to construct a stream from pure values or monadic actions.

@@ -253,6 +261,14 @@ module Streamly.Data.Stream

253261 -}

254262

255263 -- ** Scanning By 'Fold'

264+ -- | Useful idioms:

265+ --

266+ -- >>> scanl' f z = Stream.scan (Fold.foldl' f z)

267+ -- >>> scanlM' f z = Stream.scan (Fold.foldlM' f z)

268+ -- >>> postscanl' f z = Stream.postscan (Fold.foldl' f z)

269+ -- >>> postscanlM' f z = Stream.postscan (Fold.foldlM' f z)

270+ -- >>> scanl1' f = Stream.catMaybes . Stream.scan (Fold.foldl1' f)

271+ -- >>> scanl1M' f = Stream.catMaybes . Stream.scan (Fold.foldlM1' f)

256272 , scan

257273 , postscan

258274 -- XXX postscan1 can be implemented using Monoids or Refolds.

@@ -298,6 +314,13 @@ module Streamly.Data.Stream

298314 -- filtering folds (folds returning a 'Maybe' type) in

299315 -- "Streamly.Internal.Data.Fold" can be used along with 'scanMaybe' to

300316 -- perform stateful filtering operations in general.

317+ --

318+ -- Useful idioms:

319+ --

320+ -- >>> deleteBy cmp x = Stream.scanMaybe (Fold.deleteBy cmp x)

321+ -- >>> findIndices p = Stream.scanMaybe (Fold.findIndices p)

322+ -- >>> elemIndices a = findIndices (== a)

323+ -- >>> uniq = Stream.scanMaybe (Fold.uniqBy (==))

301324 , scanMaybe

302325 , take

303326 , takeWhile

@@ -399,6 +422,14 @@ module Streamly.Data.Stream

399422 , concatMapM

400423

401424 -- * Repeated Fold

425+ -- | Useful idioms:

426+ --

427+ -- >>> splitWithSuffix p f = Stream.foldMany (Fold.takeEndBy p f)

428+ -- >>> splitOnSuffix p f = Stream.foldMany (Fold.takeEndBy_ p f)

429+ -- >>> groupsBy eq f = Stream.parseMany (Parser.groupBy eq f)

430+ -- >>> groupsByRolling eq f = Stream.parseMany (Parser.groupByRolling eq f)

431+ -- >>> wordsBy p f = Stream.parseMany (Parser.wordBy p f)

432+ -- >>> groupsOf n f = Stream.foldMany (Fold.take n f)

402433 , foldMany -- XXX Rename to foldRepeat

403434 , parseMany

404435 , Array.chunksOf

@@ -574,8 +605,3 @@ import Prelude

574605--

575606-- 'Stream' and 'StreamK' types can be interconverted. See

576607-- "Streamly.Data.StreamK" module for conversion operations.

577−--

578−-- == Useful Idioms

579−--

580−-- >>> fromListM = Stream.sequence . Stream.fromList

581−-- >>> fromIndices f = fmap f $ Stream.enumerateFrom 0

core/src/Streamly/Data/StreamK.hs+6

@@ -14,6 +14,12 @@

1414--

1515-- Please refer to "Streamly.Internal.Data.Stream.StreamK" for more functions

1616-- that have not yet been released.

17+--

18+-- Some useful idioms:

19+--

20+-- >>> concatFoldableWith f = Prelude.foldr f StreamK.nil

21+-- >>> concatMapFoldableWith f g = Prelude.foldr (f . g) StreamK.nil

22+-- >>> concatForFoldableWith f xs g = Prelude.foldr (f . g) StreamK.nil xs

1723

1824-- Notes:

1925--

src/Streamly/Internal/Data/Stream/Concurrent.hs+12−1

@@ -132,6 +132,7 @@ import Streamly.Internal.Data.Stream.Concurrent.Channel

132132-- >>> import qualified Streamly.Data.Array as Array

133133-- >>> import qualified Streamly.Data.Fold as Fold

134134-- >>> import qualified Streamly.Data.Parser as Parser

135+-- >>> import qualified Streamly.Data.StreamK as StreamK

135136-- >>> import qualified Streamly.Internal.Data.Stream as Stream hiding (append2)

136137-- >>> import qualified Streamly.Internal.Data.Stream.Concurrent as Stream

137138-- >>> import Prelude hiding (concatMap, concat, zipWith)

@@ -176,6 +177,10 @@ parEvalD modifier m = D.Stream step Nothing

176177-- multiple streams won't apply here e.g. maxThreads, eager, interleaved,

177178-- ordered, stopWhen options won't have any effect.

178179--

180+-- Useful idioms:

181+--

182+-- >>> parUnfoldrM step = Stream.parEval id . Stream.unfoldrM step

183+-- >>> parIterateM step = Stream.parEval id . Stream.iterateM step

179184{-# INLINE parEval #-}

180185parEval :: MonadAsync m => (Config -> Config) -> Stream m a -> Stream m a

181186parEval modifier input = withChannel modifier input (const id)

@@ -539,9 +544,15 @@ parMapM :: MonadAsync m =>

539544 (Config -> Config) -> (a -> m b) -> Stream m a -> Stream m b

540545parMapM modifier f = parConcatMap modifier (Stream.fromEffect . f)

541546

542−-- |

547+-- | Definition:

548+--

543549-- >>> parSequence modifier = Stream.parMapM modifier id

544550--

551+-- Useful idioms:

552+--

553+-- >>> parFromListM = Stream.parSequence id . Stream.fromList

554+-- >>> parFromFoldableM = Stream.parSequence id . StreamK.toStream . StreamK.fromFoldable

555+--

545556{-# INLINE parSequence #-}

546557parSequence :: MonadAsync m =>

547558 (Config -> Config) -> Stream m (m a) -> Stream m a