on master help sign in
Improve documentation of scan routines and "before"
9148b4dHarendra Kumar
.github/workflows/haskell.yml+1−1
@@ -158,7 +158,7 @@ jobs:
158 cabal update
158 cabal update
159 cabal build all
159 cabal build all
160 $HOME/.cabal/bin/cabal-docspec --version
160 $HOME/.cabal/bin/cabal-docspec --version
161− $HOME/.cabal/bin/cabal-docspec --timeout 60
161+ $HOME/.cabal/bin/cabal-docspec --timeout 60 --check-properties --property-variables xs
162 elif test -z "$COVERAGE"
162 elif test -z "$COVERAGE"
163 then
163 then
164 export TOOLS_DIR=/opt
164 export TOOLS_DIR=/opt
src/Streamly/Internal/Data/Stream/IsStream/Common.hs+2
@@ -313,6 +313,8 @@ scanlMAfter' step initial done stream =
313-- XXX this needs to be concurrent
313-- XXX this needs to be concurrent
314-- | Like 'postscanl'' but with a monadic step function and a monadic seed.
314-- | Like 'postscanl'' but with a monadic step function and a monadic seed.
315--
315--
316+-- >>> postscanlM' f z xs = Stream.drop 1 $ Stream.scanlM' f z xs
317+--
316-- /Since: 0.7.0/
318-- /Since: 0.7.0/
317--
319--
318-- /Since: 0.8.0 (signature change)/
320-- /Since: 0.8.0 (signature change)/
src/Streamly/Internal/Data/Stream/IsStream/Exception.hs+9−1
@@ -34,13 +34,21 @@ import Streamly.Internal.Data.SVar (MonadAsync)
34
34
35import qualified Streamly.Internal.Data.Stream.StreamD as D
35import qualified Streamly.Internal.Data.Stream.StreamD as D
36
36
37+-- $setup
38+-- >>> :m
39+-- >>> import qualified Streamly.Prelude as Stream
40+-- >>> import qualified Streamly.Internal.Data.Stream.IsStream as Stream (nilM)
41+
37------------------------------------------------------------------------------
42------------------------------------------------------------------------------
38-- Exceptions
43-- Exceptions
39------------------------------------------------------------------------------
44------------------------------------------------------------------------------
40
45
41-- | Run the action @m b@ before the stream yields its first element.
46-- | Run the action @m b@ before the stream yields its first element.
42--
47--
48+-- Same as the following but more efficient due to fusion:
49+--
43−-- > before action xs = 'nilM' action <> xs
50+-- >>> before action xs = Stream.nilM action <> xs
51+-- >>> before action xs = Stream.concatMap (const xs) (Stream.fromEffect action)
44--
52--
45-- @since 0.7.0
53-- @since 0.7.0
46{-# INLINE before #-}
54{-# INLINE before #-}
src/Streamly/Internal/Data/Stream/IsStream/Transform.hs+5−1
@@ -713,6 +713,9 @@ scanlM' step begin m = fromStreamD $ D.scanlM' step begin $ toStreamD m
713-- lazy expressions inside the accumulator, it is recommended that a strict
713-- lazy expressions inside the accumulator, it is recommended that a strict
714-- data structure is used for accumulator.
714-- data structure is used for accumulator.
715--
715--
716+-- >>> scanl' f z xs = scanlM' (\a b -> return (f a b)) (return z) xs
717+-- >>> scanl' f z xs = z `Stream.cons` postscanl' f z xs
718+--
716-- See also: 'usingStateT'
719-- See also: 'usingStateT'
717--
720--
718-- @since 0.2.0
721-- @since 0.2.0
@@ -722,7 +725,8 @@ scanl' step z m = fromStreamS $ S.scanl' step z $ toStreamS m
722
725
723-- | Like 'scanl'' but does not stream the initial value of the accumulator.
726-- | Like 'scanl'' but does not stream the initial value of the accumulator.
724--
727--
728+-- >>> postscanl' f z = postscanlM' (\a b -> return (f a b)) (return z)
725−-- > postscanl' f z xs = Stream.drop 1 $ Stream.scanl' f z xs
729+-- >>> postscanl' f z xs = Stream.drop 1 $ Stream.scanl' f z xs
726--
730--
727-- @since 0.7.0
731-- @since 0.7.0
728{-# INLINE postscanl' #-}
732{-# INLINE postscanl' #-}