Iterator docs: Iterator::fold

An iterator method that applies a function, producing a single final value.

fold() takes two arguments: an initial value, and a closure that itself takes two arguments: an 'accumulator', and an element.

The job of the closure is to incrementally produce the final value to return. Starting with the initial value as the accumulator, fold() will feed the accumulator and the next element from the iterator to the closure. The closure will then return the next value to use as the accumulator.

Once the closure has been applied to every element of the iterator, fold() returns the accumulator as the final value.

Examples

Basic usage:

let a = [1, 2, 3];
    
let sum = a.iter().fold(0, |acc, elem| acc + elem);

assert_eq!(6, sum);

To see what's going on, we can use dbg! and watch fold() progress:

let a = [1, 2, 3];
    
let sum = a.iter().fold(0, |acc, elem| {
    dbg!(acc);
    dbg!(elem);

    dbg!(acc + elem)
});

assert_eq!(6, sum);

This emits output showing the closure running three times (once for each element) and the acc incrementing by elem each time:

acc = 0
elem = 1
acc + elem = 1

acc = 1
elem = 2
acc + elem = 3

acc = 3
elem = 3
acc + elem = 6

fold() can be combined with other adapters, but is typically the last call in a chain:

let a = [1, 2, 3, 4, 5];

let sum_of_even = a
    .iter()
    .filter(|elem| elem % 2 == 0)
    .fold(0, |acc, elem| acc + elem);

assert_eq!(6, sum_of_even);

A call to fold() like:

let a = [1, 2, 3];
    
let sum = a.iter().fold(0, |acc, elem| acc + elem);

is equivalent to:

let a = [1, 2, 3];

let sum = {
    let mut acc = 0;

    for elem in &a {
        acc = acc + elem;
    }

    acc
};

Related methods

• reduce(): like fold(), but uses the first element in the iterator as the initial value.
• min/max/sum: useful methods based on fold().

Note to Implementors

Several of the other (forward) methods have default implementations in terms of this one, so try to implement this explicitly if it can do something better than the default for loop implementation.

In particular, try to have this call fold() on the internal parts from which this iterator is composed.