Copyright | (c) Roman Leshchinskiy 2008-2010 |
---|---|

License | BSD-style |

Maintainer | Roman Leshchinskiy <rl@cse.unsw.edu.au> |

Stability | experimental |

Portability | non-portable |

Safe Haskell | None |

Language | Haskell2010 |

Monadic stream combinators.

## Synopsis

- data Stream m a = forall s. Stream (s -> m (Step s a)) s
- data Step s a where
- data SPEC
- length :: Monad m => Stream m a -> m Int
- null :: Monad m => Stream m a -> m Bool
- empty :: Monad m => Stream m a
- singleton :: Monad m => a -> Stream m a
- cons :: Monad m => a -> Stream m a -> Stream m a
- snoc :: Monad m => Stream m a -> a -> Stream m a
- replicate :: Monad m => Int -> a -> Stream m a
- replicateM :: Monad m => Int -> m a -> Stream m a
- generate :: Monad m => Int -> (Int -> a) -> Stream m a
- generateM :: Monad m => Int -> (Int -> m a) -> Stream m a
- (++) :: Monad m => Stream m a -> Stream m a -> Stream m a
- head :: Monad m => Stream m a -> m a
- last :: Monad m => Stream m a -> m a
- (!!) :: Monad m => Stream m a -> Int -> m a
- (!?) :: Monad m => Stream m a -> Int -> m (Maybe a)
- slice :: Monad m => Int -> Int -> Stream m a -> Stream m a
- init :: Monad m => Stream m a -> Stream m a
- tail :: Monad m => Stream m a -> Stream m a
- take :: Monad m => Int -> Stream m a -> Stream m a
- drop :: Monad m => Int -> Stream m a -> Stream m a
- map :: Monad m => (a -> b) -> Stream m a -> Stream m b
- mapM :: Monad m => (a -> m b) -> Stream m a -> Stream m b
- mapM_ :: Monad m => (a -> m b) -> Stream m a -> m ()
- trans :: (Monad m, Monad m') => (forall z. m z -> m' z) -> Stream m a -> Stream m' a
- unbox :: Monad m => Stream m (Box a) -> Stream m a
- concatMap :: Monad m => (a -> Stream m b) -> Stream m a -> Stream m b
- flatten :: Monad m => (a -> m s) -> (s -> m (Step s b)) -> Stream m a -> Stream m b
- indexed :: Monad m => Stream m a -> Stream m (Int, a)
- indexedR :: Monad m => Int -> Stream m a -> Stream m (Int, a)
- zipWithM_ :: Monad m => (a -> b -> m c) -> Stream m a -> Stream m b -> m ()
- zipWithM :: Monad m => (a -> b -> m c) -> Stream m a -> Stream m b -> Stream m c
- zipWith3M :: Monad m => (a -> b -> c -> m d) -> Stream m a -> Stream m b -> Stream m c -> Stream m d
- zipWith4M :: Monad m => (a -> b -> c -> d -> m e) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e
- zipWith5M :: Monad m => (a -> b -> c -> d -> e -> m f) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f
- zipWith6M :: Monad m => (a -> b -> c -> d -> e -> f -> m g) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f -> Stream m g
- zipWith :: Monad m => (a -> b -> c) -> Stream m a -> Stream m b -> Stream m c
- zipWith3 :: Monad m => (a -> b -> c -> d) -> Stream m a -> Stream m b -> Stream m c -> Stream m d
- zipWith4 :: Monad m => (a -> b -> c -> d -> e) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e
- zipWith5 :: Monad m => (a -> b -> c -> d -> e -> f) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f
- zipWith6 :: Monad m => (a -> b -> c -> d -> e -> f -> g) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f -> Stream m g
- zip :: Monad m => Stream m a -> Stream m b -> Stream m (a, b)
- zip3 :: Monad m => Stream m a -> Stream m b -> Stream m c -> Stream m (a, b, c)
- zip4 :: Monad m => Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m (a, b, c, d)
- zip5 :: Monad m => Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m (a, b, c, d, e)
- zip6 :: Monad m => Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f -> Stream m (a, b, c, d, e, f)
- eqBy :: Monad m => (a -> b -> Bool) -> Stream m a -> Stream m b -> m Bool
- cmpBy :: Monad m => (a -> b -> Ordering) -> Stream m a -> Stream m b -> m Ordering
- filter :: Monad m => (a -> Bool) -> Stream m a -> Stream m a
- filterM :: Monad m => (a -> m Bool) -> Stream m a -> Stream m a
- uniq :: (Eq a, Monad m) => Stream m a -> Stream m a
- mapMaybe :: Monad m => (a -> Maybe b) -> Stream m a -> Stream m b
- mapMaybeM :: Monad m => (a -> m (Maybe b)) -> Stream m a -> Stream m b
- catMaybes :: Monad m => Stream m (Maybe a) -> Stream m a
- takeWhile :: Monad m => (a -> Bool) -> Stream m a -> Stream m a
- takeWhileM :: Monad m => (a -> m Bool) -> Stream m a -> Stream m a
- dropWhile :: Monad m => (a -> Bool) -> Stream m a -> Stream m a
- dropWhileM :: Monad m => (a -> m Bool) -> Stream m a -> Stream m a
- elem :: (Monad m, Eq a) => a -> Stream m a -> m Bool
- notElem :: (Monad m, Eq a) => a -> Stream m a -> m Bool
- find :: Monad m => (a -> Bool) -> Stream m a -> m (Maybe a)
- findM :: Monad m => (a -> m Bool) -> Stream m a -> m (Maybe a)
- findIndex :: Monad m => (a -> Bool) -> Stream m a -> m (Maybe Int)
- findIndexM :: Monad m => (a -> m Bool) -> Stream m a -> m (Maybe Int)
- foldl :: Monad m => (a -> b -> a) -> a -> Stream m b -> m a
- foldlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> m a
- foldl1 :: Monad m => (a -> a -> a) -> Stream m a -> m a
- foldl1M :: Monad m => (a -> a -> m a) -> Stream m a -> m a
- foldM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> m a
- fold1M :: Monad m => (a -> a -> m a) -> Stream m a -> m a
- foldl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> m a
- foldlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> m a
- foldl1' :: Monad m => (a -> a -> a) -> Stream m a -> m a
- foldl1M' :: Monad m => (a -> a -> m a) -> Stream m a -> m a
- foldM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> m a
- fold1M' :: Monad m => (a -> a -> m a) -> Stream m a -> m a
- foldr :: Monad m => (a -> b -> b) -> b -> Stream m a -> m b
- foldrM :: Monad m => (a -> b -> m b) -> b -> Stream m a -> m b
- foldr1 :: Monad m => (a -> a -> a) -> Stream m a -> m a
- foldr1M :: Monad m => (a -> a -> m a) -> Stream m a -> m a
- and :: Monad m => Stream m Bool -> m Bool
- or :: Monad m => Stream m Bool -> m Bool
- concatMapM :: Monad m => (a -> m (Stream m b)) -> Stream m a -> Stream m b
- unfoldr :: Monad m => (s -> Maybe (a, s)) -> s -> Stream m a
- unfoldrM :: Monad m => (s -> m (Maybe (a, s))) -> s -> Stream m a
- unfoldrN :: Monad m => Int -> (s -> Maybe (a, s)) -> s -> Stream m a
- unfoldrNM :: Monad m => Int -> (s -> m (Maybe (a, s))) -> s -> Stream m a
- unfoldrExactN :: Monad m => Int -> (s -> (a, s)) -> s -> Stream m a
- unfoldrExactNM :: Monad m => Int -> (s -> m (a, s)) -> s -> Stream m a
- iterateN :: Monad m => Int -> (a -> a) -> a -> Stream m a
- iterateNM :: Monad m => Int -> (a -> m a) -> a -> Stream m a
- prescanl :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a
- prescanlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a
- prescanl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a
- prescanlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a
- postscanl :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a
- postscanlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a
- postscanl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a
- postscanlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a
- scanl :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a
- scanlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a
- scanl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a
- scanlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a
- scanl1 :: Monad m => (a -> a -> a) -> Stream m a -> Stream m a
- scanl1M :: Monad m => (a -> a -> m a) -> Stream m a -> Stream m a
- scanl1' :: Monad m => (a -> a -> a) -> Stream m a -> Stream m a
- scanl1M' :: Monad m => (a -> a -> m a) -> Stream m a -> Stream m a
- enumFromStepN :: (Num a, Monad m) => a -> a -> Int -> Stream m a
- enumFromTo :: (Enum a, Monad m) => a -> a -> Stream m a
- enumFromThenTo :: (Enum a, Monad m) => a -> a -> a -> Stream m a
- toList :: Monad m => Stream m a -> m [a]
- fromList :: Monad m => [a] -> Stream m a
- fromListN :: Monad m => Int -> [a] -> Stream m a

# Documentation

Monadic streams

Result of taking a single step in a stream

`SPEC`

is used by GHC in the `SpecConstr`

pass in order to inform
the compiler when to be particularly aggressive. In particular, it
tells GHC to specialize regardless of size or the number of
specializations. However, not all loops fall into this category.

Libraries can specify this by using `SPEC`

data type to inform which
loops should be aggressively specialized.

# Length

# Construction

replicateM :: Monad m => Int -> m a -> Stream m a Source #

Yield a `Stream`

of values obtained by performing the monadic action the
given number of times

generateM :: Monad m => Int -> (Int -> m a) -> Stream m a Source #

Generate a stream from its indices

# Accessing elements

(!?) :: Monad m => Stream m a -> Int -> m (Maybe a) infixl 9 Source #

Element at the given position or `Nothing`

if out of bounds

# Substreams

Extract a substream of the given length starting at the given position.

# Mapping

mapM :: Monad m => (a -> m b) -> Stream m a -> Stream m b Source #

Map a monadic function over a `Stream`

mapM_ :: Monad m => (a -> m b) -> Stream m a -> m () Source #

Execute a monadic action for each element of the `Stream`

trans :: (Monad m, Monad m') => (forall z. m z -> m' z) -> Stream m a -> Stream m' a Source #

Transform a `Stream`

to use a different monad

# Zipping

indexed :: Monad m => Stream m a -> Stream m (Int, a) Source #

Pair each element in a `Stream`

with its index

indexedR :: Monad m => Int -> Stream m a -> Stream m (Int, a) Source #

Pair each element in a `Stream`

with its index, starting from the right
and counting down

zipWithM :: Monad m => (a -> b -> m c) -> Stream m a -> Stream m b -> Stream m c Source #

Zip two `Stream`

s with the given monadic function

zipWith3M :: Monad m => (a -> b -> c -> m d) -> Stream m a -> Stream m b -> Stream m c -> Stream m d Source #

zipWith4M :: Monad m => (a -> b -> c -> d -> m e) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e Source #

zipWith5M :: Monad m => (a -> b -> c -> d -> e -> m f) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f Source #

zipWith6M :: Monad m => (a -> b -> c -> d -> e -> f -> m g) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f -> Stream m g Source #

zipWith3 :: Monad m => (a -> b -> c -> d) -> Stream m a -> Stream m b -> Stream m c -> Stream m d Source #

zipWith4 :: Monad m => (a -> b -> c -> d -> e) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e Source #

zipWith5 :: Monad m => (a -> b -> c -> d -> e -> f) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f Source #

zipWith6 :: Monad m => (a -> b -> c -> d -> e -> f -> g) -> Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f -> Stream m g Source #

zip4 :: Monad m => Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m (a, b, c, d) Source #

zip5 :: Monad m => Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m (a, b, c, d, e) Source #

zip6 :: Monad m => Stream m a -> Stream m b -> Stream m c -> Stream m d -> Stream m e -> Stream m f -> Stream m (a, b, c, d, e, f) Source #

# Comparisons

eqBy :: Monad m => (a -> b -> Bool) -> Stream m a -> Stream m b -> m Bool Source #

Check if two `Stream`

s are equal

cmpBy :: Monad m => (a -> b -> Ordering) -> Stream m a -> Stream m b -> m Ordering Source #

Lexicographically compare two `Stream`

s

# Filtering

filter :: Monad m => (a -> Bool) -> Stream m a -> Stream m a Source #

Drop elements which do not satisfy the predicate

filterM :: Monad m => (a -> m Bool) -> Stream m a -> Stream m a Source #

Drop elements which do not satisfy the monadic predicate

mapMaybeM :: Monad m => (a -> m (Maybe b)) -> Stream m a -> Stream m b Source #

Apply monadic function to each element and drop all Nothings

*Since: 0.12.2.0*

takeWhile :: Monad m => (a -> Bool) -> Stream m a -> Stream m a Source #

Longest prefix of elements that satisfy the predicate

takeWhileM :: Monad m => (a -> m Bool) -> Stream m a -> Stream m a Source #

Longest prefix of elements that satisfy the monadic predicate

dropWhile :: Monad m => (a -> Bool) -> Stream m a -> Stream m a Source #

Drop the longest prefix of elements that satisfy the predicate

dropWhileM :: Monad m => (a -> m Bool) -> Stream m a -> Stream m a Source #

Drop the longest prefix of elements that satisfy the monadic predicate

# Searching

elem :: (Monad m, Eq a) => a -> Stream m a -> m Bool infix 4 Source #

Check whether the `Stream`

contains an element

# Folding

foldlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> m a Source #

Left fold with a monadic operator

foldl1M :: Monad m => (a -> a -> m a) -> Stream m a -> m a Source #

Left fold over a non-empty `Stream`

with a monadic operator

foldl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> m a Source #

Left fold with a strict accumulator

foldlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> m a Source #

Left fold with a strict accumulator and a monadic operator

foldl1' :: Monad m => (a -> a -> a) -> Stream m a -> m a Source #

Left fold over a non-empty `Stream`

with a strict accumulator

foldl1M' :: Monad m => (a -> a -> m a) -> Stream m a -> m a Source #

Left fold over a non-empty `Stream`

with a strict accumulator and a
monadic operator

foldrM :: Monad m => (a -> b -> m b) -> b -> Stream m a -> m b Source #

Right fold with a monadic operator

foldr1M :: Monad m => (a -> a -> m a) -> Stream m a -> m a Source #

Right fold over a non-empty stream with a monadic operator

# Specialised folds

# Unfolding

unfoldrM :: Monad m => (s -> m (Maybe (a, s))) -> s -> Stream m a Source #

Unfold with a monadic function

unfoldrNM :: Monad m => Int -> (s -> m (Maybe (a, s))) -> s -> Stream m a Source #

Unfold at most `n`

elements with a monadic function.

unfoldrExactN :: Monad m => Int -> (s -> (a, s)) -> s -> Stream m a Source #

Unfold exactly `n`

elements

*Since: 0.12.2.0*

unfoldrExactNM :: Monad m => Int -> (s -> m (a, s)) -> s -> Stream m a Source #

Unfold exactly `n`

elements with a monadic function.

*Since: 0.12.2.0*

iterateN :: Monad m => Int -> (a -> a) -> a -> Stream m a Source #

*O(n)* Apply function \(\max(n - 1, 0)\) times to an initial value,
producing a stream of \(\max(n, 0)\) values.

iterateNM :: Monad m => Int -> (a -> m a) -> a -> Stream m a Source #

*O(n)* Apply monadic function \(\max(n - 1, 0)\) times to an initial value,
producing a stream of \(\max(n, 0)\) values.

# Scans

prescanlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a Source #

Prefix scan with a monadic operator

prescanl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a Source #

Prefix scan with strict accumulator

prescanlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a Source #

Prefix scan with strict accumulator and a monadic operator

postscanlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a Source #

Suffix scan with a monadic operator

postscanl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a Source #

Suffix scan with strict accumulator

postscanlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a Source #

Suffix scan with strict acccumulator and a monadic operator

scanlM :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a Source #

Haskell-style scan with a monadic operator

scanl' :: Monad m => (a -> b -> a) -> a -> Stream m b -> Stream m a Source #

Haskell-style scan with strict accumulator

scanlM' :: Monad m => (a -> b -> m a) -> a -> Stream m b -> Stream m a Source #

Haskell-style scan with strict accumulator and a monadic operator

scanl1M :: Monad m => (a -> a -> m a) -> Stream m a -> Stream m a Source #

Scan over a non-empty `Stream`

with a monadic operator

scanl1' :: Monad m => (a -> a -> a) -> Stream m a -> Stream m a Source #

Scan over a non-empty `Stream`

with a strict accumulator

scanl1M' :: Monad m => (a -> a -> m a) -> Stream m a -> Stream m a Source #

Scan over a non-empty `Stream`

with a strict accumulator and a monadic
operator

# Enumerations

enumFromStepN :: (Num a, Monad m) => a -> a -> Int -> Stream m a Source #

Yield a `Stream`

of the given length containing the values `x`

, `x+y`

,
`x+y+y`

etc.

enumFromTo :: (Enum a, Monad m) => a -> a -> Stream m a Source #

Enumerate values

*WARNING:* This operation can be very inefficient. If at all possible, use
`enumFromStepN`

instead.

enumFromThenTo :: (Enum a, Monad m) => a -> a -> a -> Stream m a Source #

Enumerate values with a given step.

*WARNING:* This operation is very inefficient. If at all possible, use
`enumFromStepN`

instead.