Iterators

What do managers and Rust iterators have in common?
They can both look very productive while doing absolutely nothing.

Rust iterators are lazy: they don't do any work until you ask for a result. That's great, because it means you can chain together many operations without creating intermediate collections.

You can filter, transform, and combine values in a single pipeline. And once you get the hang of it, you'll find that iterators are often more readable than a for loop. That's because you don't have to manage indexes or check bounds yourself; it's all part of Rust's ergonomic iterator machinery, one of my favorite parts of the language.

Here's how iterators work in practice:

1. Get an iterator with .iter(), .into_iter(), .iter_mut(), or directly from .chars(), .lines(), etc.
2. Chain adapters like .map(...), .filter(...), .take(...). These are lazy.
3. Finish with a consumer like .collect(), .sum(), .count(), .any(...), or a for loop.

let words = vec!["hello", "café", "rust"];

let lengths: Vec<usize> = words
    .iter()
    .map(|word| word.chars().count())
    .collect();
assert_eq!(lengths, vec![5, 4, 4]);

The three "iter" methods differ in what they yield:

• .iter() yields &T (immutable references). Use when reading.
• .iter_mut() yields &mut T. Use when modifying in place.
• .into_iter() on an owned Vec<T> consumes the vector and yields T. On borrowed collections, it yields references instead: &T for &Vec<T> and &mut T for &mut Vec<T>.

Some adapters change the item type. Here, iter yields &&str, but map produces character counts of type usize. The compiler infers types through the chain. You can write the chain first, then add a type annotation on the binding if the compiler needs one.

.collect() can produce many different collections. Tell it which one with a type annotation: Vec<_>, HashMap<_, _>, String. The _ lets the compiler fill in the inner types.

Coming Back to Word Count

Remember the three little functions from the word count chapter's exercise break? Each one was a counter, a for loop, and a return. With iterators, the whole trio shrinks to:

fn word_count(text: &str)   -> usize { text.split_whitespace().count() }
fn char_count(text: &str)   -> usize { text.chars().count() }
fn longest_word(text: &str) -> usize {
    text.split_whitespace().map(|w| w.chars().count()).max().unwrap_or(0)
}

You no longer have to maintain the mut counters or keep track of the maximum yourself.

Summing with an Iterator

A short warmup: calculate the total sales with an iterator consumer. The later exercises will combine consumers with adapters that change or select items.

You could add the values with a for loop and an accumulator. Here, sum asks the iterator for each value and collapses the sequence into one total.

Useful from the Standard Library

• <[T]>::iter produces an iterator of shared references over the slice.
• Iterator::sum reduces a numeric iterator to a single total. The function's i32 return type supplies its output type when you return the result directly. In other contexts, you may need an annotation (let total: i32 = ...) or the turbofish (.sum::<i32>()).

Transforming with `map`

Normalize every email address to lowercase, preserving the input order. Unlike summing, this keeps one output for each input. Write an iterator pipeline that returns the new vector.

map is lazy: it just describes the transformation. Nothing runs until collect (or another consumer) asks for the results.

Useful from the Standard Library

• Vec::into_iter consumes the vec and yields owned items. The input vector is no longer needed after this call. to_lowercase only borrows each string, so ownership is not required for the conversion itself.
• Iterator::map applies a closure to each item and produces a new iterator with the transformed items.
• Iterator::collect turns the pipeline back into a collection. The return type (Vec<String>) tells collect which collection to produce.
• str::to_lowercase returns a fresh String with characters converted to lowercase. Lowercasing is not the same as Unicode case folding for caseless comparison.

Keeping Elements with `filter`

With map you transformed every item, while filter keeps some items and drops the rest. There is one borrowing detail to watch: usernames.into_iter() yields &str, and filter gives its closure a reference to each item, so the closure sees &&str.

Method calls such as s.starts_with(...) automatically dereference these layers. The extra references can be hard to track at first. If the compiler reports a missing &, check what the iterator yields and what the closure receives. The iterators entry in the cheatsheet shows those reference layers side by side.

Useful from the Standard Library

• Iterator::filter keeps only items where the predicate returns true. The closure receives a reference to the item, regardless of whether the iterator yields owned values or borrows.
• str::starts_with takes a char (or another &str) and answers yes/no. Method-call syntax auto-derefs through the extra reference.
• collect() here picks Vec<&str> straight from the return type. You don't need a turbofish here.

Filter, Then Own the Result

This time the input is a &[&str], a borrowed slice of borrowed strings, so the iterator yields &&str. You'll return owned Strings so the caller can keep the results independently of the input. That lets us focus on the iterator chain without adding lifetime annotations.

Combine what you've used so far to return only paths ending in .rs, in their original order. An empty input or no matching paths should give an empty vector. This time, choose how the adapters fit together yourself.

Useful from the Standard Library

• Iterator::filter borrows each item for its predicate. When the iterator yields &&str, the predicate receives &&&str. String method calls auto-deref through these layers.
• Iterator::map can change the item type by applying a closure to each item.
• str::to_string converts a borrowed string slice into an owned String. Auto-deref reaches through the extra reference for you.
• str::ends_with checks whether a string ends with a given suffix.

Revisit: Summing Parsed Numbers

In the ? chapter, you parsed each token inside a for loop. Write sum_numbers again, this time with an iterator pipeline and sum, without a loop or ?. Keep the same behavior: whitespace separates integers, empty input returns Ok(0), and the first parse error ends the sum. Assume the running total fits in an i32.

Iterator::sum also works on an iterator of Result values. Its output can be a Result containing either the total or the first error. The function's return type can tell it which output type to use.

Compare the two versions after the tests pass. In the loop, ? returns from sum_numbers when parsing fails. Here, sum stops asking for items and returns an Err to its caller; it does not return from the surrounding function. Your function can inspect that result or return it directly. Adding ? after sum would propagate an error that sum has already found.

Predict, Then Run: How Far Does It Go?

The tests below already contain the pipelines. Before running them, replace each todo!() with your prediction; leave the pipelines unchanged.

For the first test, predict how many times the closure runs when nothing consumes the iterator. For the second, predict the first result, the collected batch, the next result, and the inputs visited by map. Write down the order of the printed messages too. Then run the tests and compare the trace with your predictions. Locally, use cargo test --example 17_iterators _8_lazy_consumption:: -- --nocapture to see output from passing tests.

• next asks for one item and returns an Option.
• by_ref lets a consumer borrow an iterator so you can use it again afterward.
• take limits how many items its consumer can request.

Does asking for one filtered result visit just one input? After collecting the batch, does the next call start over or resume? Try changing take(1) to take(2), predict all the results again, and rerun.

Wrapping Up Iterators

You summed a numeric array with sum, transformed every element with map, kept just the matching ones with filter, and combined filter with map to convert borrowed slices into owned strings.

What We Learned

• An iterator pipeline starts with .iter(), .iter_mut(), .into_iter(), or a method such as .chars() or .lines(). Lazy adapters describe what should happen to each item. A consumer finishes the pipeline by asking for results.

• iter yields &T, and iter_mut yields &mut T. On an owned Vec<T>, into_iter consumes the vector and yields T. On borrowed collections, it yields references instead: &T for &Vec<T> and &mut T for &mut Vec<T>. Pick the one that matches what you intend to do with each item.

• Adapters (map, filter, take, skip, ...) describe the pipeline but do nothing on their own. The actual work happens when a consumer (collect, sum, count, for loop) asks for results.

• collect is generic over the target collection. The return type (or a turbofish like .collect::<Vec<_>>()) tells it what to build.

• sum needs to know its output type. The function's return type can supply it; otherwise annotate the binding or use .sum::<i32>().

• filter's closure always takes &T, so on a &str iterator you'll see &&str. Method calls auto-deref, so .starts_with(...) works through extra references; comparison operators sometimes need an explicit *.

• The |x| ... syntax you've been seeing is a closure: an anonymous function passed as an argument.

• Fallible sum stops at the first Err and returns it as a value. Unlike ?, it doesn't return from the surrounding function.

• next and take can consume only part of a pipeline. With by_ref, you can resume the same iterator afterward; already-consumed items don't run again.