# 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.