Rust iterators and adapters.

A Vec has three methods that make an iterator over its elements. They differ in what each item is:

• cities.iter() gives a shared reference to each element, a &String. cities keeps all its elements.
• cities.iter_mut() gives a mutable reference to each element, a &mut String, so the code can change the elements in place. The Vec must be declared with let mut.
• cities.into_iter() gives the elements themselves, each a String. It takes cities by value: the Vec moves into the iterator, and each element moves out to the code that receives it.

After into_iter(), cities cannot be used again. The compiler reports:

error[E0382]: borrow of moved value: `cities`

with “`cities` moved due to this method call” under into_iter() and the note “this function takes ownership of the receiver `self`, which moves `cities`”.

So use iter() to read the elements, iter_mut() to change them in place, and into_iter() when the collection is no longer needed and its elements should go somewhere else, such as into another Vec.

iter() lends each element (&T), iter_mut() lends it for changing (&mut T), and into_iter() hands over each element (T) and uses up the collection.

Each adapter, such as map or filter, returns a new iterator and runs nothing, as Map, filter, and reduce showed. That has one trap that the compiler does not stop.

map looks like a way to change every element: nights.iter_mut().map(|n| *n += 1);. This statement builds a Map iterator that holds the closure, and drops it at the end of the statement. Nothing asks the Map for an item, so the closure never runs, and nights keeps its old values. The program compiles. rustc prints a compiler warning, a message about code that compiles but looks like a mistake:

warning: unused `Map` that must be used

with the note “iterators are lazy and do nothing unless consumed”. The stepper does not show Rust warnings; cargo build or cargo check in a terminal does.

To run a closure for each element, end the chain with a consumer: a method that asks for values and returns something that is not an iterator. for_each(|n| *n += 1) asks for every item and calls the closure with it. A for loop does the same, and is often easier to read when the body changes things.

An adapter with no consumer after it never runs its closure; rustc warns, and the program runs without the change.

An adapter takes the items of the iterator before it and passes on new items. Each adapter wraps the one before, so a chain is read from left to right:

• map(f) passes on f(item) for each item.
• filter(test) passes on the items for which test returns true.
• enumerate() passes on pairs (index, item), counting from 0.
• zip(other) passes on pairs (item, item of other), and ends when either side ends.
• take(n) passes on the first n items; skip(n) leaves out the first n.
• chain(other) passes on all the items, then all the items of other.
• rev() passes on the items from the last to the first.

An adapter sees only what reaches it. enumerate counts the items it receives, so after skip(1), the first item it receives gets the number 0. To number items by their place in the collection, put enumerate first.

Each closure receives what its adapter gives it. map’s closure receives the item itself. filter’s closure only tests the item, so it receives a reference to it, &Item. With iter(), the item is already a &i32, so filter’s closure gets a &&i32: a reference to a reference. Comparing it with a number fails:

error[E0308]: mismatched types

with “expected `&&_`, found integer”. Write **n > 1 to follow both references, or take them off in the closure’s parameter: in |&&n| n > 1, the pattern &&n matches the two references, and n is the i32. Rust closure capture and Fn traits covers what a closure captures; this is only about its parameter.

Each adapter works on what the adapter before it passes on: enumerate counts what it receives, and filter’s closure receives a reference to each item.

A consumer asks the chain for values and returns something that is not an iterator. Each one decides how many values it asks for:

• collect() asks for every value and builds a collection. It can build a Vec, a String, a HashMap, and more, so it needs to know which: let more: Vec<u32> = … .collect(); or … .collect::<Vec<u32>>(). The ::<…> after a method name gives the type for that call; Vec<_> lets the compiler work out the element type. With no type at all, the compiler reports error[E0282]: type annotations needed, with help: consider giving `more` an explicit type.
• sum() and count() ask for every value. sum needs its type too, and gives 0 when there are no values. count gives the number of values.
• fold(start, f), from Map, filter, and reduce, asks for every value.
• any(test) and all(test) give a bool. any stops at the first item that passes; all stops at the first item that fails.
• find(test) gives Some(the first item that passes), or None, and stops there. position(test) gives Some(its index) or None, counting from 0 in the iterator it is called on.

A consumer takes the iterator by value: the iterator moves into the call and is used up. Calling a second consumer on the same iterator, long.count() and then long.sum(), gives error[E0382]: use of moved value: `long`. Make a new iterator for each pass, such as nights.iter(); it costs almost nothing.

A consumer runs the chain and uses up the iterator. collect and sum need to know their result type, and any, all, find, and position stop at the first answer.

parse, from Printing values and reading input, returns a Result: Ok(value) for success or Err(error) for failure. A chain that parses each item passes on Results. Collected into a Vec<Result<u32, _>>, they stay one Result per item, and the code must look at each one.

collect can also build one Result from many. Ask for Result<Vec<u32>, _>. While every item is Ok, collect keeps the values in a Vec. At the first Err, it stops asking for items and returns that Err. The items after it are never read, and the closures before collect never run for them. So the whole result is Ok(all the values) or the first error.

Option works the same way: collecting Options into Option<Vec<u32>> gives Some(all the values), or None at the first None. sum works this way too: sum::<Result<u32, _>>() gives Ok(the total) or the first Err.

Collect Results into Result<Vec<_>, _> to get every value or the first error; the items after the first error are never read.

Four mistakes with iterators are common in real code.

Errors left out without a word. filter_map(|t| t.parse::<u32>().ok()) keeps the numbers that parse and leaves out the rest: ok() turns an Err into None, and filter_map drops each None. When bad input must be reported, a total computed this way is too low, and nobody is told. Collect into a Result instead, or count what was left out.

zip on lists of different lengths. zip ends when the shorter side ends, with no error. If one list lost an item, the last items of the other list are left out of the result. When two lists must match, compare their lengths before zipping them.

A side effect inside any, all, find, or position. These stop at the first answer, so a closure that also prints, logs, or counts runs for some items only. Do the effect in a for loop, and make the decision separately.

Collecting references where owned values are needed. cities.iter() gives &String, so collecting it into a Vec<String> gives error[E0277]: a value of type `Vec<String>` cannot be built from an iterator over elements of type `&String`, as Composition and data transformation showed for &str. Add .cloned() to copy each String, or use into_iter() when cities is no longer needed.

Report errors instead of filtering them out, compare lengths before zip, keep side effects out of closures that may stop early, and copy or hand over elements when the result must own them.

The chain below walks the nights from the last to the first, keeps the long stays, and stops after two. A counter shows how often filter’s closure runs.