In Rust, why does `lines.iter().map(parse)` on its own run no code, and what makes the chain actually execute?
answer
- adapters return a new struct
- nobody calls next yet
- must_use on Map
- a consumer drives the chain
basics
~20 sAn adapter such as map only wraps the source iterator and the closure in a new struct; no closure runs until a consumer such as collect, sum, count, for_each or a for loop calls next. rustc warns when the chain is dropped unused.
solid answer
~40 s`map`, `filter`, `zip`, `take_while` and the other adapters take the iterator by value and return a new struct, such as `Map<I, F>`, that stores the source and the closure. Building it does no work. Work happens only when something calls `Iterator::next`: a consumer like `collect`, `sum`, `count`, `fold`, `find`, `for_each`, or a `for` loop. Each `next()` on the outermost adapter produces one item, pulling from the source only as far as it needs to. std marks its adapter structs `#[must_use = "iterators are lazy and do nothing unless consumed"]`, so the statement `lines.iter().map(parse);` compiles with the warning ``unused `Map` that must be used``, and `parse` is never called. If the closure exists for its side effect, use `for_each` or a `for` loop instead.
code
rust · 16 linesfn status(line: &str) -> u16 {
println!("parsing {line}");
line.rsplit(' ').next().unwrap().parse().unwrap()
}
fn main() {
let lines = ["ERROR auth 500", "INFO web 200", "ERROR web 503"];
lines.iter().map(|l| status(l)); // warning: unused `Map` that must be used
let codes = lines.iter().map(|l| status(l));
println!("chain built");
let total: u32 = codes.map(u32::from).sum();
println!("total {total}");
}go deeper
Say plainly that adapters build a value and consumers do the work, and name a few of each. Mention the unused Map warning as the compiler catching a forgotten consumer.
Explain the pull model: the consumer calls next on the outer adapter, which calls next on its inner iterator, one item at a time. Note that consumers take self, so a chain is spent afterwards.
Tie laziness to what it buys in production code: no intermediate allocations, infinite or streaming sources, and early exit. Point out the side-effect-in-map bug as a review catch.
Frame laziness as an API property: functions returning iterators let callers decide how much work happens, while a function that collects eagerly fixes that cost for every caller.
## What an adapter actually returns In Rust an **iterator** is any type implementing the `Iterator` trait, whose one required method is `next(&mut self) -> Option<Self::Item>`. Calling `next` either produces the next item (`Some(item)`) or reports the end (`None`). An **adapter** is an `Iterator` method that takes the iterator by value and returns *another* iterator. `map` returns `Map<I, F>`, `filter` returns `Filter<I, P>`, `zip` returns `Zip<A, B>`, `flat_map` returns `FlatMap<I, U, F>`. Each of these is a plain struct holding two things: - the iterator it wraps, and - the closure (or second iterator) it was given. Constructing that struct is the whole cost of calling the adapter. No element is read, no closure is called, nothing is allocated for the items. A chain such as `lines.iter().filter(is_error).map(parse)` is a nested value — a `Map` around a `Filter` around a slice iterator — waiting for someone to ask it for an item. ## Who calls `next`: the consumers A **consumer** is a method that keeps calling `next` until it has its answer. `collect` into an ordinary collection, `sum` of plain numbers, `count`, `fold`, `for_each`, `last` and `max` keep going until `None`; `find`, `any`, `all` and `position` may stop early. A `for` loop is a consumer too: it turns its operand into an iterator and calls `next` until `None` or a `break`. | Kind | Examples | Calls the closures? | |---|---|---| | Adapter | `map`, `filter`, `filter_map`, `flat_map`, `zip`, `enumerate`, `take_while`, `skip`, `chain` | No — returns a new iterator struct | | Consumer | `collect`, `sum`, `count`, `fold`, `for_each`, `find`, `any`, `all` | Yes — pulls items until done | When a consumer calls `next` on the outer `Map`, `Map::next` calls `next` on the inner `Filter`, which calls `next` on the slice iterator until it finds a line its predicate accepts, and then `Map` applies its closure to that one line. One item travels the full chain per call. ## Seeing it in a log analyser The program below parses status codes from log lines. The statement that builds `codes` prints nothing; the parse messages appear only when `sum` starts pulling: ```rust let codes = lines.iter().map(|l| status(l)); println!("chain built"); // printed first let total: u32 = codes.map(u32::from).sum(); // now status() runs, once per line ``` The output is `chain built`, then one `parsing ...` line per log line, then the total. Because `sum` takes the iterator by value, `codes` is used up afterwards; to process the lines again you build a new chain from `lines`. ## The compiler's warning std's adapter structs carry the attribute `#[must_use = "iterators are lazy and do nothing unless consumed"]`. When a statement builds one and throws it away, rustc's `unused_must_use` lint fires: 1. It reports ``unused `Map` that must be used``. 2. It adds the note `iterators are lazy and do nothing unless consumed`. 3. It suggests `let _ = ...` if you really meant to discard it. If the closure returns `()` — `lines.iter().map(|l| println!("{l}"));` — a second lint, `map_unit_fn`, also fires and suggests `Iterator::for_each`. Both are warnings, not errors: the program compiles and silently does nothing at that line. ## Why the design is lazy Laziness is what makes chains cheap to compose: - No intermediate `Vec` is built between `filter` and `map`; each item flows straight through. - Infinite sources are usable: `(1..).map(f).take(10)` is fine, because only ten items are ever pulled. - A consumer that stops early, such as `find`, stops the whole chain, so later items are never read. - After inlining, the optimiser usually fuses the nested `next` calls of a `map`-`filter`-`sum` chain into a single loop, so the layering costs nothing at run time in the common case. The same rule explains why a function can return an iterator cheaply: it hands back the unrun chain, and the caller decides how much of it to pull. ## Traps worth knowing - Writing `map` for a side effect (logging, pushing into a `Vec`) and never consuming it: nothing happens. Use `for_each` or a `for` loop. - Expecting a chain to run twice: consumers take `self`, so a chain is spent after one consumer. Rebuild it, or `collect` once and reuse the collection. - Assuming the closure has already run when you inspect captured state right after building the chain — it has not. - Calling `count` or `collect` on an infinite chain: these consumers only stop at `None`, so they never return. - Forgetting that an unconsumed chain still holds its borrow: `let errors = lines.iter().filter(..);` keeps `lines` borrowed for as long as `errors` is used later, which can block a mutation of `lines` in between.
- Why does `lines.iter().map(|l| println!("{l}"));` produce two warnings instead of one?The `unused_must_use` lint reports the discarded `Map`, because std marks adapter structs `#[must_use]`. The separate `map_unit_fn` lint notices that the closure returns `()`, so the resulting iterator carries no data, and suggests `Iterator::for_each`. Neither stops compilation, and neither line prints anything.
- Is `(1..).map(|n| n * n)` a problem, given that the range never ends?Not by itself. Building the chain pulls nothing, so an infinite source costs nothing until consumed. `take(5).collect::<Vec<_>>()` pulls five items and stops. Calling `count`, `sum` or an unbounded `collect` on it would never return, because those consumers only stop at `None`.
- map runs its closure over every element as soon as it is called
- The chain runs automatically when the statement ends
- The unused Map warning is cosmetic and the closure still ran
- Each adapter builds an intermediate Vec for the next stage
- A chain can be consumed twice because it remembers its items