Streamly.Prelude

This module is designed to be imported qualified:

import qualified Streamly.Prelude as S

Functions with the suffix M are general functions that work on monadic arguments. The corresponding functions without the suffix M work on pure arguments and can in general be derived from their monadic versions but are provided for convenience and for consistency with other pure APIs in the base package.

Deconstruction and folds accept a SerialT type instead of a polymorphic type to ensure that streams always have a concrete monomorphic type by default, reducing type errors. In case you want to use any other type of stream you can use one of the type combinators provided in the Streamly module to convert the stream type.

Construction

Primitives to construct or inspect a stream.

nil :: IsStream t => t m a

An empty stream.

> toList nil
[]

Since: 0.1.0

consM :: (IsStream t, Monad m) => m a -> t m a -> t m a infixr 5

Constructs a stream by adding a monadic action at the head of an existing stream. For example:

> toList $ getLine `consM` getLine `consM` nil
hello
world
["hello","world"]

Since: 0.2.0

(|:) :: (IsStream t, Monad m) => m a -> t m a -> t m a infixr 5

Operator equivalent of consM.

> toList $ getLine |: getLine |: nil
hello
world
["hello","world"]

Since: 0.2.0

cons :: IsStream t => a -> t m a -> t m a infixr 5

Construct a stream by adding a pure value at the head of an existing stream. Same as consM . return. For example:

> toList $ 1 `cons` 2 `cons` 3 `cons` nil
[1,2,3]

Since: 0.1.0

(.:) :: IsStream t => a -> t m a -> t m a infixr 5

Operator equivalent of cons.

> toList $ 1 .: 2 .: 3 .: nil
[1,2,3]

Since: 0.1.1

General Unfold

unfoldr :: IsStream t => (b -> Maybe (a, b)) -> b -> t m a

Build a Stream by unfolding pure steps starting from a seed.

Since: 0.1.0

unfoldrM :: (IsStream t, Monad m) => (b -> m (Maybe (a, b))) -> b -> t m a

Build a Stream by unfolding monadic steps starting from a seed.

Since: 0.1.0

Special Generation

Generate a monadic stream from an input structure, a seed or a generation function.

once :: (IsStream t, Monad m) => m a -> t m a

Create a singleton stream by executing a monadic action once. Same as m `consM` nil but more efficient.

> toList $ once getLine
hello
["hello"]

Since: 0.2.0

replicateM :: (IsStream t, Monad m) => Int -> m a -> t m a

Generate a stream by performing a monadic action n times.

Since: 0.1.1

repeatM :: (IsStream t, Monad m) => m a -> t m a

Generate a stream by repeatedly executing a monadic action forever.

Since: 0.2.0

iterate :: IsStream t => (a -> a) -> a -> t m a

Iterate a pure function from a seed value, streaming the results forever.

Since: 0.1.2

iterateM :: (IsStream t, Monad m) => (a -> m a) -> a -> t m a

Iterate a monadic function from a seed value, streaming the results forever.

Since: 0.1.2

fromFoldable :: (IsStream t, Foldable f) => f a -> t m a

Construct a stream from a Foldable container.

Since: 0.2.0

Deconstruction

uncons :: (IsStream t, Monad m) => SerialT m a -> m (Maybe (a, t m a))

Decompose a stream into its head and tail. If the stream is empty, returns Nothing. If the stream is non-empty, returns 'Just (a, ma)', where a is the head of the stream and ma its tail.

Since: 0.1.0

Folding

General Folds

foldr :: Monad m => (a -> b -> b) -> b -> SerialT m a -> m b

Lazy right associative fold. For example, to fold a stream into a list:

>> runIdentity $ foldr (:) [] (serially $ fromFoldable [1,2,3])
[1,2,3]

Since: 0.1.0

foldrM :: Monad m => (a -> b -> m b) -> b -> SerialT m a -> m b

Lazy right fold with a monadic step function. For example, to fold a stream into a list:

>> runIdentity $ foldrM (\x xs -> return (x : xs)) [] (serially $ fromFoldable [1,2,3])
[1,2,3]

Since: 0.2.0

foldl' :: Monad m => (b -> a -> b) -> b -> SerialT m a -> m b

Strict left associative fold.

Since: 0.2.0

foldlM' :: Monad m => (b -> a -> m b) -> b -> SerialT m a -> m b

Like foldl' but with a monadic step function.

Since: 0.2.0

foldx :: Monad m => (x -> a -> x) -> x -> (x -> b) -> SerialT m a -> m b

Strict left fold with an extraction function. Like the standard strict left fold, but applies a user supplied extraction function (the third argument) to the folded value at the end. This is designed to work with the foldl library. The suffix x is a mnemonic for extraction.

Since: 0.2.0

foldxM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> SerialT m a -> m b

Like foldx, but with a monadic step function.

Since: 0.2.0

Special Folds

mapM_ :: Monad m => (a -> m b) -> SerialT m a -> m ()

Apply a monadic action to each element of the stream and discard the output of the action.

Since: 0.1.0

toList :: Monad m => SerialT m a -> m [a]

Convert a stream into a list in the underlying monad.

Since: 0.1.0

all :: Monad m => (a -> Bool) -> SerialT m a -> m Bool

Determine whether all elements of a stream satisfy a predicate.

Since: 0.1.0

any :: Monad m => (a -> Bool) -> SerialT m a -> m Bool

Determine whether any of the elements of a stream satisfy a predicate.

Since: 0.1.0

head :: Monad m => SerialT m a -> m (Maybe a)

Extract the first element of the stream, if any.

Since: 0.1.0

tail :: (IsStream t, Monad m) => SerialT m a -> m (Maybe (t m a))

Extract all but the first element of the stream, if any.

Since: 0.1.1

last :: Monad m => SerialT m a -> m (Maybe a)

Extract the last element of the stream, if any.

Since: 0.1.1

null :: Monad m => SerialT m a -> m Bool

Determine whether the stream is empty.

Since: 0.1.1

length :: Monad m => SerialT m a -> m Int

Determine the length of the stream.

Since: 0.1.0

elem :: (Monad m, Eq a) => a -> SerialT m a -> m Bool

Determine whether an element is present in the stream.

Since: 0.1.0

notElem :: (Monad m, Eq a) => a -> SerialT m a -> m Bool

Determine whether an element is not present in the stream.

Since: 0.1.0

maximum :: (Monad m, Ord a) => SerialT m a -> m (Maybe a)

Determine the maximum element in a stream.

Since: 0.1.0

minimum :: (Monad m, Ord a) => SerialT m a -> m (Maybe a)

Determine the minimum element in a stream.

Since: 0.1.0

sum :: (Monad m, Num a) => SerialT m a -> m a

Determine the sum of all elements of a stream of numbers

Since: 0.1.0

product :: (Monad m, Num a) => SerialT m a -> m a

Determine the product of all elements of a stream of numbers

Since: 0.1.1

Scans

scanl' :: IsStream t => (b -> a -> b) -> b -> t m a -> t m b

Strict left scan. Like foldl', but returns the folded value at each step, generating a stream of all intermediate fold results. The first element of the stream is the user supplied initial value, and the last element of the stream is the same as the result of foldl'.

Since: 0.2.0

scanx :: IsStream t => (x -> a -> x) -> x -> (x -> b) -> t m a -> t m b

Strict left scan with an extraction function. Like scanl', but applies a user supplied extraction function (the third argument) at each step. This is designed to work with the foldl library. The suffix x is a mnemonic for extraction.

Since: 0.2.0

Filtering

filter :: IsStream t => (a -> Bool) -> t m a -> t m a

Include only those elements that pass a predicate.

Since: 0.1.0

take :: IsStream t => Int -> t m a -> t m a

Take first n elements from the stream and discard the rest.

Since: 0.1.0

takeWhile :: IsStream t => (a -> Bool) -> t m a -> t m a

End the stream as soon as the predicate fails on an element.

Since: 0.1.0

drop :: IsStream t => Int -> t m a -> t m a

Discard first n elements from the stream and take the rest.

Since: 0.1.0

dropWhile :: IsStream t => (a -> Bool) -> t m a -> t m a

Drop elements in the stream as long as the predicate succeeds and then take the rest of the stream.

Since: 0.1.0

Reordering

reverse :: IsStream t => t m a -> t m a

Returns the elements of the stream in reverse order. The stream must be finite.

Since: 0.1.1

Mapping

mapM :: (IsStream t, Monad m) => (a -> m b) -> t m a -> t m b

Replace each element of the stream with the result of a monadic action applied on the element.

Since: 0.1.0

sequence :: (IsStream t, Monad m) => t m (m a) -> t m a

Reduce a stream of monadic actions to a stream of the output of those actions.

Since: 0.1.0

Zipping

zipWith :: IsStream t => (a -> b -> c) -> t m a -> t m b -> t m c

Zip two streams serially using a pure zipping function.

Since: 0.1.0

zipWithM :: IsStream t => (a -> b -> t m c) -> t m a -> t m b -> t m c

Zip two streams serially using a monadic zipping function.

Since: 0.1.0

zipAsyncWith :: (IsStream t, MonadAsync m) => (a -> b -> c) -> t m a -> t m b -> t m c

Zip two streams concurrently (i.e. both the elements being zipped are generated concurrently) using a pure zipping function.

Since: 0.1.0

zipAsyncWithM :: (IsStream t, MonadAsync m) => (a -> b -> t m c) -> t m a -> t m b -> t m c

Zip two streams asyncly (i.e. both the elements being zipped are generated concurrently) using a monadic zipping function.

Since: 0.1.0

IO

fromHandle :: (IsStream t, MonadIO m) => Handle -> t m String

Read lines from an IO Handle into a stream of Strings.

Since: 0.1.0

toHandle :: MonadIO m => Handle -> SerialT m String -> m ()

Write a stream of Strings to an IO Handle.

Since: 0.1.0

Deprecated

each :: (IsStream t, Foldable f) => f a -> t m a

Deprecated: Please use fromFoldable instead.

Same as fromFoldable.

Since: 0.1.0

scan :: IsStream t => (x -> a -> x) -> x -> (x -> b) -> t m a -> t m b

Deprecated: Please use scanx instead.

Since: 0.1.1

foldl :: Monad m => (x -> a -> x) -> x -> (x -> b) -> SerialT m a -> m b

Deprecated: Please use foldx instead.

Since: 0.1.0

foldlM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> SerialT m a -> m b

Deprecated: Please use foldxM instead.

Since: 0.1.0