The type Fold m a b having constructor Fold step initial extract represents a fold over an input stream of values of type a to a final value of type b in Monad m.

The fold uses an intermediate state s as accumulator, the type s is internal to the specific fold definition. The initial value of the fold state s is returned by initial. The step function consumes an input and either returns the final result b if the fold is done or the next intermediate state (see Step). At any point the fold driver can extract the result from the intermediate state using the extract function.

NOTE: The constructor is not yet exposed via exposed modules, smart constructors are provided to create folds. If you think you need the constructor of this type please consider using the smart constructors in Streamly.Internal.Data.Fold instead.

since 0.8.0 (type changed)

Since: 0.7.0

Make a fold from a left fold style pure step function and initial value of the accumulator.

If your Fold returns only Partial (i.e. never returns a Done) then you can use foldl'* constructors.

A fold with an extract function can be expressed using fmap:

mkfoldlx :: Monad m => (s -> a -> s) -> s -> (s -> b) -> Fold m a b
mkfoldlx step initial extract = fmap extract (foldl' step initial)

See also: Streamly.Prelude.foldl'

Since: 0.8.0

Make a fold from a left fold style monadic step function and initial value of the accumulator.

A fold with an extract function can be expressed using rmapM:

mkFoldlxM :: Functor m => (s -> a -> m s) -> m s -> (s -> m b) -> Fold m a b
mkFoldlxM step initial extract = rmapM extract (foldlM' step initial)

See also: Streamly.Prelude.foldlM'

Since: 0.8.0

Make a fold using a right fold style step function and a terminal value. It performs a strict right fold via a left fold using function composition. Note that this is strict fold, it can only be useful for constructing strict structures in memory. For reductions this will be very inefficient.

For example,

toList = foldr (:) []

See also: foldr

Since: 0.8.0

Append the elements of an input stream to a provided starting value.

>>> Stream.fold (Fold.sconcat 10) (Stream.map Data.Monoid.Sum $ Stream.enumerateFromTo 1 10)
Sum {getSum = 65}

sconcat = Fold.foldl' (<>)

Since: 0.8.0

Fold an input stream consisting of monoidal elements using mappend and mempty.

>>> Stream.fold Fold.mconcat (Stream.map Data.Monoid.Sum $ Stream.enumerateFromTo 1 10)
Sum {getSum = 55}

mconcat = Fold.sconcat mempty

Since: 0.7.0

foldMap f = Fold.lmap f Fold.mconcat

Make a fold from a pure function that folds the output of the function using mappend and mempty.

>>> Stream.fold (Fold.foldMap Data.Monoid.Sum) $ Stream.enumerateFromTo 1 10
Sum {getSum = 55}

Since: 0.7.0

foldMapM f = Fold.lmapM f Fold.mconcat

Make a fold from a monadic function that folds the output of the function using mappend and mempty.

>>> Stream.fold (Fold.foldMapM (return . Data.Monoid.Sum)) $ Stream.enumerateFromTo 1 10
Sum {getSum = 55}

Since: 0.7.0

A fold that drains all its input, running the effects and discarding the results.

drain = drainBy (const (return ()))

Since: 0.7.0

drainBy f = lmapM f drain
drainBy = Fold.foldMapM (void . f)

Drain all input after passing it through a monadic function. This is the dual of mapM_ on stream producers.

See also: mapM_

Since: 0.7.0

Extract the last element of the input stream, if any.

last = fmap getLast $ Fold.foldMap (Last . Just)

Since: 0.7.0

Determine the length of the input stream.

length = fmap getSum $ Fold.foldMap (Sum . const  1)

Since: 0.7.0

Determine the sum of all elements of a stream of numbers. Returns additive identity (0) when the stream is empty. Note that this is not numerically stable for floating point numbers.

sum = fmap getSum $ Fold.foldMap Sum

Since: 0.7.0

Determine the product of all elements of a stream of numbers. Returns multiplicative identity (1) when the stream is empty. The fold terminates when it encounters (0) in its input.

Compare with Fold.foldMap Product.

Since 0.8.0 (Added Eq constraint)

Since: 0.7.0

Determine the maximum element in a stream using the supplied comparison function.

Since: 0.7.0

maximum = Fold.maximumBy compare

Determine the maximum element in a stream.

Compare with Fold.foldMap Max.

Since: 0.7.0

Computes the minimum element with respect to the given comparison function

Since: 0.7.0

Determine the minimum element in a stream using the supplied comparison function.

minimum = minimumBy compare

Compare with Fold.foldMap Min.

Since: 0.7.0

Compute a numerically stable arithmetic mean of all elements in the input stream.

Since: 0.7.0

Compute a numerically stable (population) variance over all elements in the input stream.

Since: 0.7.0

Compute a numerically stable (population) standard deviation over all elements in the input stream.

Since: 0.7.0

Compute an Int sized polynomial rolling hash of a stream.

rollingHash = Fold.rollingHashWithSalt defaultSalt

Since: 0.8.0

Compute an Int sized polynomial rolling hash

H = salt * k ^ n + c1 * k ^ (n - 1) + c2 * k ^ (n - 2) + ... + cn * k ^ 0

Where c1, c2, cn are the elements in the input stream and k is a constant.

This hash is often used in Rabin-Karp string search algorithm.

See https://en.wikipedia.org/wiki/Rolling_hash

Since: 0.8.0

Folds the input stream to a list.

Warning! working on large lists accumulated as buffers in memory could be very inefficient, consider using Streamly.Data.Array.Foreign instead.

toList = foldr (:) []

Since: 0.7.0

Buffers the input stream to a list in the reverse order of the input.

toListRev = Fold.foldl' (flip (:)) []

Warning! working on large lists accumulated as buffers in memory could be very inefficient, consider using Streamly.Array instead.

Since: 0.8.0

Lookup the element at the given index.

See also: !!

Since: 0.7.0

Extract the first element of the stream, if any.

Since: 0.7.0

Returns the first element that satisfies the given predicate.

Since: 0.7.0

In a stream of (key-value) pairs (a, b), return the value b of the first pair where the key equals the given value a.

lookup = snd <$> Fold.find ((==) . fst)

Since: 0.7.0

Returns the first index that satisfies the given predicate.

Since: 0.7.0

Returns the first index where a given value is found in the stream.

elemIndex a = Fold.findIndex (== a)

Since: 0.7.0

Return True if the input stream is empty.

null = fmap isJust Fold.head

Since: 0.7.0

Return True if the given element is present in the stream.

elem a = Fold.any (== a)

Since: 0.7.0

Returns True if the given element is not present in the stream.

notElem a = Fold.all (/= a)

Since: 0.7.0

Returns True if all elements of a stream satisfy a predicate.

>>> Stream.fold (Fold.all (== 0)) $ Stream.fromList [1,0,1]
False

all p = Fold.lmap p Fold.and

Since: 0.7.0

Returns True if any of the elements of a stream satisfies a predicate.

>>> Stream.fold (Fold.any (== 0)) $ Stream.fromList [1,0,1]
True

any p = Fold.lmap p Fold.or

Since: 0.7.0

Returns True if all elements are True, False otherwise

and = Fold.all (== True)

Since: 0.7.0

Returns True if any element is True, False otherwise

or = Fold.any (== True)

Since: 0.7.0

Map a monadic function on the output of a fold.

Since: 0.8.0

lmap f fold maps the function f on the input of the fold.

>>> Stream.fold (Fold.lmap (\x -> x * x) Fold.sum) (Stream.enumerateFromTo 1 100)
338350

lmap = Fold.lmapM return

Since: 0.8.0

lmapM f fold maps the monadic function f on the input of the fold.

Since: 0.8.0

Include only those elements that pass a predicate.

>>> Stream.fold (Fold.filter (> 5) Fold.sum) $ Stream.fromList [1..10]
40

filter f = Fold.filterM (return . f)

Since: 0.8.0

Like filter but with a monadic predicate.

Since: 0.8.0

Modify a fold to receive a Maybe input, the Just values are unwrapped and sent to the original fold, Nothing values are discarded.

Since: 0.8.0

mapMaybe f fold maps a Maybe returning function f on the input of the fold, filters out Nothing elements, and return the values extracted from Just.

>>> f x = if even x then Just x else Nothing
>>> fld = Fold.mapMaybe f Fold.toList
>>> Stream.fold fld (Stream.enumerateFromTo 1 10)
[2,4,6,8,10]

Since: 0.8.0

Take at most n input elements and fold them using the supplied fold. A negative count is treated as 0.

>>> Stream.fold (Fold.take 2 Fold.toList) $ Stream.fromList [1..10]
[1,2]

Since: 0.8.0

Like takeEndBy but drops the element on which the predicate succeeds.

>>> Stream.fold (Fold.takeEndBy_ (== '\n') Fold.toList) $ Stream.fromList "hello\nthere\n"
"hello"

>>> Stream.toList $ Stream.foldMany (Fold.takeEndBy_ (== '\n') Fold.toList) $ Stream.fromList "hello\nthere\n"
["hello","there"]

Stream.splitOnSuffix p f = Stream.foldMany (Fold.takeEndBy_ p f)

See splitOnSuffix for more details on splitting a stream using takeEndBy_.

Since: 0.8.0

Take the input, stop when the predicate succeeds taking the succeeding element as well.

>>> Stream.fold (Fold.takeEndBy (== '\n') Fold.toList) $ Stream.fromList "hello\nthere\n"
"hello\n"

>>> Stream.toList $ Stream.foldMany (Fold.takeEndBy (== '\n') Fold.toList) $ Stream.fromList "hello\nthere\n"
["hello\n","there\n"]

Stream.splitWithSuffix p f = Stream.foldMany (Fold.takeEndBy p f)

See splitWithSuffix for more details on splitting a stream using takeEndBy.

Since: 0.8.0

Sequential fold application. Apply two folds sequentially to an input stream. The input is provided to the first fold, when it is done - the remaining input is provided to the second fold. When the second fold is done or if the input stream is over, the outputs of the two folds are combined using the supplied function.

>>> f = Fold.serialWith (,) (Fold.take 8 Fold.toList) (Fold.takeEndBy (== '\n') Fold.toList)
>>> Stream.fold f $ Stream.fromList "header: hello\n"
("header: ","hello\n")

Note: This is dual to appending streams using serial.

Note: this implementation allows for stream fusion but has quadratic time complexity, because each composition adds a new branch that each subsequent fold's input element has to traverse, therefore, it cannot scale to a large number of compositions. After around 100 compositions the performance starts dipping rapidly compared to a CPS style implementation.

Time: O(n^2) where n is the number of compositions.

Since: 0.8.0

teeWith k f1 f2 distributes its input to both f1 and f2 until both of them terminate and combines their output using k.

>>> avg = Fold.teeWith (/) Fold.sum (fmap fromIntegral Fold.length)
>>> Stream.fold avg $ Stream.fromList [1.0..100.0]
50.5

teeWith k f1 f2 = fmap (uncurry k) ((Fold.tee f1 f2)

For applicative composition using this combinator see Streamly.Internal.Data.Fold.Tee.

See also: Streamly.Internal.Data.Fold.Tee

Since: 0.8.0

Distribute one copy of the stream to each fold and zip the results.

                |-------Fold m a b--------|
---stream m a---|                         |---m (b,c)
                |-------Fold m a c--------|

>>> Stream.fold (Fold.tee Fold.sum Fold.length) (Stream.enumerateFromTo 1.0 100.0)
(5050.0,100)

tee = teeWith (,)

Since: 0.7.0

Distribute one copy of the stream to each fold and collect the results in a container.

                |-------Fold m a b--------|
---stream m a---|                         |---m [b]
                |-------Fold m a b--------|
                |                         |
                           ...

>>> Stream.fold (Fold.distribute [Fold.sum, Fold.length]) (Stream.enumerateFromTo 1 5)
[15,5]

distribute = Prelude.foldr (Fold.teeWith (:)) (Fold.fromPure [])

This is the consumer side dual of the producer side sequence operation.

Stops when all the folds stop.

Since: 0.7.0

Compose two folds such that the combined fold accepts a stream of Either and routes the Left values to the first fold and Right values to the second fold.

partition = partitionBy id

Since: 0.7.0

Send the elements of tuples in a stream of tuples through two different folds.

                          |-------Fold m a x--------|
---------stream of (a,b)--|                         |----m (x,y)
                          |-------Fold m b y--------|

unzip = Fold.unzipWith id

This is the consumer side dual of the producer side zip operation.

Since: 0.7.0

Collect zero or more applications of a fold. many split collect applies the split fold repeatedly on the input stream and accumulates zero or more fold results using collect.

>>> two = Fold.take 2 Fold.toList
>>> twos = Fold.many two Fold.toList
>>> Stream.fold twos $ Stream.fromList [1..10]
[[1,2],[3,4],[5,6],[7,8],[9,10]]

Stops when collect stops.

See also: concatMap, foldMany

Since: 0.8.0

chunksOf n split collect repeatedly applies the split fold to chunks of n items in the input stream and supplies the result to the collect fold.

>>> twos = Fold.chunksOf 2 Fold.toList Fold.toList
>>> Stream.fold twos $ Stream.fromList [1..10]
[[1,2],[3,4],[5,6],[7,8],[9,10]]

chunksOf n split = many (take n split)

Stops when collect stops.

Since: 0.8.0

Map a Fold returning function on the result of a Fold and run the returned fold. This operation can be used to express data dependencies between fold operations.

Let's say the first element in the stream is a count of the following elements that we have to add, then:

>>> import Data.Maybe (fromJust)
>>> count = fmap fromJust Fold.head
>>> total n = Fold.take n Fold.sum
>>> Stream.fold (Fold.concatMap total count) $ Stream.fromList [10,9..1]
45

Time: O(n^2) where n is the number of compositions.

See also: foldIterateM

Since: 0.8.0

Flatten the monadic output of a fold to pure output.

Since: 0.7.0

Map a monadic function on the output of a fold.

Since: 0.7.0