foldl package:base

Left-associative fold of a structure, lazy in the accumulator. This is rarely what you want, but can work well for structures with efficient right-to-left sequencing and an operator that is lazy in its left argument. In the case of lists, foldl, when applied to a binary operator, a starting value (typically the left-identity of the operator), and a list, reduces the list using the binary operator, from left to right:

foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn

Note that to produce the outermost application of the operator the entire input list must be traversed. Like all left-associative folds, foldl will diverge if given an infinite list. If you want an efficient strict left-fold, you probably want to use foldl' instead of foldl. The reason for this is that the latter does not force the inner results (e.g. z `f` x1 in the above example) before applying them to the operator (e.g. to (`f` x2)). This results in a thunk chain O(n) elements long, which then must be evaluated from the outside-in. For a general Foldable structure this should be semantically identical to:

foldl f z = foldl f z . toList

Examples

The first example is a strict fold, which in practice is best performed with foldl'.

>>> foldl (+) 42 [1,2,3,4]
52

Though the result below is lazy, the input is reversed before prepending it to the initial accumulator, so corecursion begins only after traversing the entire input string.

>>> foldl (\acc c -> c : acc) "abcd" "efgh"
"hgfeabcd"

A left fold of a structure that is infinite on the right cannot terminate, even when for any finite input the fold just returns the initial accumulator:

>>> foldl (\a _ -> a) 0 $ repeat 1
* Hangs forever *

WARNING: When it comes to lists, you always want to use either foldl' or foldr instead.

foldl, applied to a binary operator, a starting value (typically the left-identity of the operator), and a list, reduces the list using the binary operator, from left to right:

foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn

The list must be finite.

>>> foldl (+) 0 [1..4]
10

>>> foldl (+) 42 []
42

>>> foldl (-) 100 [1..4]
90

>>> foldl (\reversedString nextChar -> nextChar : reversedString) "foo" ['a', 'b', 'c', 'd']
"dcbafoo"

>>> foldl (+) 0 [1..]
* Hangs forever *

Left-associative fold of a structure but with strict application of the operator. This ensures that each step of the fold is forced to Weak Head Normal Form before being applied, avoiding the collection of thunks that would otherwise occur. This is often what you want to strictly reduce a finite structure to a single strict result (e.g. sum). For a general Foldable structure this should be semantically identical to,

foldl' f z = foldl' f z . toList

A variant of foldl that has no base case, and thus may only be applied to non-empty structures. This function is non-total and will raise a runtime exception if the structure happens to be empty.

foldl1 f = foldl1 f . toList

Examples

Basic usage:

>>> foldl1 (+) [1..4]
10

>>> foldl1 (+) []
*** Exception: Prelude.foldl1: empty list

>>> foldl1 (+) Nothing
*** Exception: foldl1: empty structure

>>> foldl1 (-) [1..4]
-8

>>> foldl1 (&&) [True, False, True, True]
False

>>> foldl1 (||) [False, False, True, True]
True

>>> foldl1 (+) [1..]
* Hangs forever *

A strict version of foldl1.

Left-to-right monadic fold over the elements of a structure. Given a structure t with elements (a, b, ..., w, x, y), the result of a fold with an operator function f is equivalent to:

foldlM f z t = do
aa <- f z a
bb <- f aa b
...
xx <- f ww x
yy <- f xx y
return yy -- Just @return z@ when the structure is empty

For a Monad m, given two functions f1 :: a -> m b and f2 :: b -> m c, their Kleisli composition (f1 >=> f2) :: a -> m c is defined by:

(f1 >=> f2) a = f1 a >>= f2

Another way of thinking about foldlM is that it amounts to an application to z of a Kleisli composition:

foldlM f z t =
flip f a >=> flip f b >=> ... >=> flip f x >=> flip f y $ z

The monadic effects of foldlM are sequenced from left to right. If at some step the bind operator (>>=) short-circuits (as with, e.g., mzero in a MonadPlus), the evaluated effects will be from an initial segment of the element sequence. If you want to evaluate the monadic effects in right-to-left order, or perhaps be able to short-circuit after processing a tail of the sequence of elements, you'll need to use foldrM instead. If the monadic effects don't short-circuit, the outermost application of f is to the rightmost element y, so that, ignoring effects, the result looks like a left fold:

((((z `f` a) `f` b) ... `f` w) `f` x) `f` y

Examples

Basic usage:

>>> let f a e = do { print e ; return $ e : a }

>>> foldlM f [] [0..3]
0
1
2
3
[3,2,1,0]

A variant of foldlMap1 where the leftmost element maps to itself.

A variant of foldlMap1' where the leftmost element maps to itself.

Monadic fold over the elements of a non-empty structure, associating to the left, i.e. from left to right.

Left-associative fold of a structure, lazy in the accumulator. This is rarely what you want, but can work well for structures with efficient right-to-left sequencing and an operator that is lazy in its left argument. In case of NonEmpty lists, foldlMap1, when given a function f, a binary operator g, and a list, reduces the list using g from left to right applying f to the leftmost element:

foldlMap1 f g (x1 :| [x2, ..., xn]) == (...(((f x1) `g` x2) `g`...) `g` xn

Note that to produce the outermost application of the operator the entire input list must be traversed. This means that foldlMap1 will diverge if given an infinite list. If you want an efficient strict left-fold, you probably want to use foldlMap1' instead of foldlMap1. The reason for this is that the latter does not force the inner results (e.g. (f x1) `g` x2 in the above example) before applying them to the operator (e.g. to (`g` x3)). This results in a thunk chain <math> elements long, which then must be evaluated from the outside-in. For a general Foldable1 structure this should be semantically identical to:

foldlMap1 f g = foldlMap1 f g . toNonEmpty

Left-associative fold of a structure but with strict application of the operator. This ensures that each step of the fold is forced to Weak Head Normal Form before being applied, avoiding the collection of thunks that would otherwise occur. This is often what you want to strictly reduce a finite structure to a single strict result. For a general Foldable1 structure this should be semantically identical to:

foldlMap1' f z = foldlMap1' f z . toNonEmpty

Map variant of foldlM1.

A left fold over the elements with no starting value

A left fold over the elements

A strict left fold over the elements

A strict version of foldl.

foldl1 is a variant of foldl that has no starting value argument, and thus must be applied to non-empty lists. Note that unlike foldl, the accumulated value must be of the same type as the list elements.

>>> foldl1 (+) [1..4]
10

>>> foldl1 (+) []
*** Exception: Prelude.foldl1: empty list

>>> foldl1 (-) [1..4]
-8

>>> foldl1 (&&) [True, False, True, True]
False

>>> foldl1 (||) [False, False, True, True]
True

>>> foldl1 (+) [1..]
* Hangs forever *

Combines the elements of a structure in a left associative manner. Given a hypothetical function toEitherList :: p a b -> [Either a b] yielding a list of all elements of a structure in order, the following would hold:

bifoldl f g z
≡ foldl (acc -> either (f acc) (g acc)) z . toEitherList

Note that if you want an efficient left-fold, you probably want to use bifoldl' instead of bifoldl. The reason is that the latter does not force the "inner" results, resulting in a thunk chain which then must be evaluated from the outside-in.

Examples

Basic usage:

> bifoldl (+) (*) 3 (5, 7)
56 -- (5 + 3) * 7

> bifoldl (+) (*) 3 (7, 5)
50 -- (7 + 3) * 5

> bifoldl (+) (*) 3 (Right 5)
15 -- 5 * 3

> bifoldl (+) (*) 3 (Left 5)
8 -- 5 + 3

As bifoldl, but strict in the result of the reduction functions at each step. This ensures that each step of the bifold is forced to weak head normal form before being applied, avoiding the collection of thunks that would otherwise occur. This is often what you want to strictly reduce a finite structure to a single, monolithic result (e.g., bilength).

A variant of bifoldl that has no base case, and thus may only be applied to non-empty structures.

Examples

Basic usage:

>>> bifoldl1 (+) (5, 7)
12

>>> bifoldl1 (+) (Right 7)
7

>>> bifoldl1 (+) (Left 5)
5

> bifoldl1 (+) (BiList [1, 2] [3, 4])
10 -- ((1 + 2) + 3) + 4

>>> bifoldl1 (+) (BiList [1, 2] [])
3

On empty structures, this function throws an exception:

>>> bifoldl1 (+) (BiList [] [])
*** Exception: bifoldl1: empty structure
...

Left associative monadic bifold over a structure.

Examples

Basic usage:

>>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 ("Hello", True)
"Hello"
"True"
42

>>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 (Right True)
"True"
42

>>> bifoldlM (\a b -> print b >> pure a) (\a c -> print (show c) >> pure a) 42 (Left "Hello")
"Hello"
42

Left-associative fold operation for constructor applications. The type of gfoldl is a headache, but operationally it is a simple generalisation of a list fold. The default definition for gfoldl is const id, which is suitable for abstract datatypes with no substructures.