One item at a time

You have been writing history.iter() since lesson 6.2 without asking what it gives you. It does not give you the items. It gives you an iterator: a small value whose one job is to hand out the next item when asked, and to say when there are none left. You ask by calling next(), and the answer is an Option from lesson 5.4: Some(item), or None once the list is used up.

$ cargo run
Some("rust")
Some("is")
Some("fun")
None

Three Somes, then None. The iterator has to be mut because asking changes it: it remembers how far it has got. That is all a for loop is. for w in words.iter() means "call next(), run the body with what is inside the Some, and stop at the first None", which is the while let loop of lesson 5.5 with a nicer name.

Chapter 4 said there are three ways to hand a value over: lend it to look at, lend it to change, or give it away. A Vec has one iterator for each, and that choice is the most important thing about a walk.

You have used the first row since lesson 6.2. The middle row looks like this. Each w is an exclusive borrow of one String inside the list, so push changes that String where it lives, and the Vec, still yours, comes out with every word changed:

$ cargo run
["hi!", "hello!"]

error[E0382]: borrow of moved value: `names`
 --> src/main.rs:7:35
  |
2 |     let names = vec![String::from("sam"), String::from("ada")];
  |         ----- move occurs because `names` has type `Vec<String>`, which does not implement the `Copy` trait
3 |     let mut kept = Vec::new();
4 |     for name in names.into_iter() {
  |                       ----------- `names` moved due to this method call
...
7 |     println!("{} {}", kept.len(), names.len());
  |                                   ^^^^^ value borrowed here after move
  |
note: `std::iter::IntoIterator::into_iter` takes ownership of the receiver `self`, which moves `names`
 --> /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library/core/src/iter/traits/collect.rs:312:17
help: you can `clone` the value and consume it, but this might not be your desired behavior
  |
4 |     for name in names.clone().into_iter() {
  |                      ++++++++

Since an iterator is just "something with a next()", you can wrap one in another. These wrappers are called adapters, and each one takes a closure (lesson 6.4) that says what to do with every item:

• map(|m| …) turns each item into something else: a message into its length.
• filter(|m| …) keeps only the items for which the closure says true.
• flat_map(|m| …) turns each item into several and hands them all out in a row: a message into its words.
• take(3) hands out the first three, then says None.

An adapter does no work when you write it. It only builds a bigger iterator around the one before. Something at the end of the chain has to keep calling next(): a consumer. collect() gathers everything into a collection, sum() adds it up, count() counts it, and a for loop is a consumer too. So who runs first?

Rust calls this lazy: work happens when an answer is asked for, one item at a time, all the way down the chain. Each item travels through every step before the next item starts, so there is no list of lengths stored halfway, and a take(3) at the end really does stop the work after three.

Telling collect what to build

collect() can build many kinds of collection: a Vec, a String, a HashMap. The chain alone does not say which, so you have to.

error[E0283]: type annotations needed
 --> src/main.rs:3:9
  |
3 |     let words = said.split_whitespace().collect();
  |         ^^^^^                           ------- type must be known at this point
  |
  = note: the type must implement `FromIterator<&str>`
note: required by a bound in `collect`
 --> /rustc/b940084d7eb6a299eb4bfeb8e34901bc051e7ac4/library/core/src/iter/traits/iterator.rs:2073:4
help: consider giving `words` an explicit type
  |
3 |     let words: Vec<_> = said.split_whitespace().collect();
  |              ++++++++

Here is the whole program after this lesson, new lines in green. Two commands are rewritten as chains, and one is new.

• /count becomes one line: history.iter().map(|m| m.text.len()).sum(). The type on bytes: usize tells sum() what kind of number to add up, the same job the annotation did for collect().
• /find asks the same question as lesson 6.4, "yours, and contains the word?", but no longer keeps it in a let is_match: the closure is written straight inside filter(|m| …), where it is used. It still captures word by borrow, and here it needs no type on m, because filter already knows what it is walking. collect() gathers the hits into a Vec<&Message>: borrows pointing into the history, nothing copied. If that Vec is empty, Chatterbox says "you never said …"; otherwise a for loop prints each hit.
• /stats is new. It walks history.iter(), keeps your messages with filter, and splits each into words with flat_map(|m| m.text.split_whitespace()). A for loop consumes that chain and counts each word, lowercased so that "Rust" and "rust" are one word, with entry and or_insert from lesson 6.3.
• Then counts.into_iter().collect() turns the map into a Vec<(String, u32)> of pairs. It is into_iter on purpose: the map is not needed again, so its Strings move into the Vec instead of being copied.
• sort_by sorts with a closure that is handed two pairs, a and b, and must say which goes first. It says so with cmp, which compares two values and answers one of three words: Less, Equal or Greater. (Those three words are a type called Ordering; the other value goes in as a borrow, hence the &.) .1 is the second part of a pair, the count, and .0 the first, the word (lesson 2.6). b.1.cmp(&a.1) compares the counts with b first, so the biggest count comes first; when they are Equal, .then(a.0.cmp(&b.0)) asks a second question, the words in alphabetical order, so the answer never changes from one run to the next.
• Finally take(3) keeps the top three, map(|(word, n)| …) takes each pair apart (lesson 5.5) and turns it into text like rust (2), and collect() builds a Vec<String> to join. No words at all means "nothing said yet".

Sam
rust is fun
Rust is fast
tea
/stats
/quit

Chatterbox v0.6
What should I call you?
Hi Sam! I'm Chatterbox. Ask me anything.
bot: you said: rust is fun
bot: you said: Rust is fast
bot: you said: tea
bot: your top words: is (2), rust (2), fast (1)
bot: bye, Sam!
messages so far: 3

Sam
/stats
/quit

Chatterbox v0.6
What should I call you?
Hi Sam! I'm Chatterbox. Ask me anything.
bot: nothing said yet
bot: bye, Sam!
messages so far: 0

An iterator is a small value with a next(). iter, iter_mut and into_iter decide whether each step hands you a look, a change or the item itself, by the rules you learned in chapter 4 for handing values over. Adapters wrap iterators without doing anything; a consumer at the end pulls each item through the whole chain. Chapter 6 is done: Chatterbox keeps a history it can number, count, search and summarise, and facts it can remember by name. Next it learns to say clearly when something goes wrong.

Sources The Rust Book: processing a series of items with iterators · The Rust Book: comparing performance, loops vs. iterators · Rust standard library: the Iterator trait · Rust standard library: std::iter