Iterators

Why iterators?

Most data work is "go through a list, keep some items, change them, combine the result". You can write that with for loops and temporary variables, or describe it as a chain of small steps. The chain is often shorter, clearer and just as fast. You have already used iterators: every for loop uses one behind the scenes.

The Iterator trait

pub trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
    // ...plus dozens of provided methods: map, filter, sum, collect...
}

let v = vec![10, 20];
let mut it = v.iter();
println!("{:?}", it.next());   // Some(10)
println!("{:?}", it.next());   // Some(20)
println!("{:?}", it.next());   // None: finished

type Item is an associated type: each iterator says what kind of item it produces. A for loop simply calls next() until it gets None.

Three ways to iterate a collection

Adapters: building the chain

An adapter takes an iterator and returns a new iterator. Adapters are lazy: they do no work until something asks for items. So a chain of map and filter does nothing on its own; the compiler even warns "unused iterator that must be used".

let prices = vec![120, 45, 300, 80, 999];

let with_gst: Vec<u32> = prices.iter()
    .filter(|&&p| p >= 100)          // keep items of Rs 100 or more
    .map(|&p| p + p * 18 / 100)      // add GST
    .collect();                      // run the chain into a Vec
println!("{:?}", with_gst);          // [141, 354, 1178]

Consumers: getting a result

let marks = [72, 91, 45, 88, 30];
let total: u32 = marks.iter().sum();
let passed = marks.iter().filter(|&&m| m >= 40).count();
let top = marks.iter().max();                       // Some(91)
let any_fail = marks.iter().any(|&m| m < 33);       // true
let first_80 = marks.iter().find(|&&m| m >= 80);    // Some(91)
let product = (1..=5).fold(1, |acc, x| acc * x);    // 120
println!("{total} {passed} {:?} {any_fail} {:?} {product}", top, first_80);

collect() can build many collections: a Vec, a String, a HashMap from pairs, or a HashSet. Tell it which with a type annotation or the turbofish: collect::<Vec<_>>(). The underscore asks the compiler to fill in the item type.

Zero-cost abstraction

Rust's iterator chains are compiled into a plain loop with no extra allocations or function calls. The Rust Book shows benchmarks where the iterator version is as fast as, or slightly faster than, the hand-written loop, because the compiler can remove bounds checks. You can use the clear style without paying for it.

Common mistakes

• Writing a chain without a consumer, like v.iter().map(|x| x * 2); and wondering why nothing happened. Add collect, sum or a for loop.
• Confusing reference levels in closures (&x, &&x). Follow the compiler hints, or use .copied() to turn &u32 items into u32.
• Calling collect() without saying what to collect into: "type annotations needed".
• Using into_iter() and then trying to use the collection again.