19.3The Iterator trait

Last updated June 13, 2026

You've been iterating since chapter 7. for x in &scores walks a vector; for c in word.chars() walks the characters of a string. Underneath every one of those loops is a single small trait, and once you see it, a huge amount of the standard library stops being magic. An iterator is any value that knows how to produce a sequence of items, one at a time, on request. That's the entire idea. The trait that captures it is Iterator, and it has essentially one required method.

The trait itself

Stripped to its core, Iterator looks like this:

trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}

Two pieces. type Item is an associated type: a type that belongs to the trait and that each implementor fills in, naming the kind of thing this particular iterator yields (i32, &String, char). It's written type Item; in the trait and type Item = i32; in an implementation, and you read Self::Item as "whatever this iterator decided to yield." And next is the engine: call it, and it returns Some(item) with the next value, or None once the sequence is exhausted. The Option return (chapter 11) is how an iterator says "I'm done", there's no separate "are we finished?" call, the None is the signal.

Because next takes &mut self, calling it changes the iterator: it advances. An iterator is a stateful little machine that remembers where it is. Let's watch one run by hand:

fn main() {
    let v = vec![10, 20, 30];
    let mut it = v.iter();

    println!("{:?}", it.next());
    println!("{:?}", it.next());
    println!("{:?}", it.next());
    println!("{:?}", it.next());
}

Some(10)
Some(20)
Some(30)
None

v.iter() builds an iterator over the vector; it must be mut because each next mutates its internal position. Three Somes, then None forever after. A for loop is exactly this: call next in a loop, bind each Some value to the loop variable, stop at the first None. We'll prove that claim properly in lesson 19.6; for now, know that the loops you've written were calling next all along.

Three ways to iterate a collection

That little program called v.iter(). There are three sibling methods, and the difference between them is, once again, just chapter 8 and 9 ownership applied to iteration. Each produces items of a different type:

iter() yields shared references &T. The collection is borrowed; you can read each element but not change it, and the collection is still yours afterward.

iter_mut() yields mutable references &mut T. The collection is mutably borrowed; you can change each element in place.

into_iter() yields owned values T. The collection is consumed (moved into the iterator); you get each element by value, and the original is gone.

Here are all three:

fn main() {
    let v = vec![1, 2, 3];
    let total: i32 = v.iter().sum();      // &i32 each; v still usable
    println!("sum is {total}, v is {v:?}");

    let mut v2 = vec![1, 2, 3];
    for n in v2.iter_mut() {              // &mut i32 each
        *n *= 10;
    }
    println!("{v2:?}");

    let v3 = vec![String::from("a"), String::from("b")];
    for s in v3.into_iter() {            // String each, by value; v3 consumed
        println!("owning {s}");
    }
    // v3 is gone here.
}

sum is 6, v is [1, 2, 3]
[10, 20, 30]
owning a
owning b

This is why for x in &v and for x in v behave differently, and you've felt it without naming it. &v calls iter() (borrow, x is &T), &mut v calls iter_mut(), and a bare v calls into_iter() (consume, x is T). Choosing the loop header chooses the ownership mode. The owned form is the one you want when you need to take the elements out, for example to move each String somewhere else; the borrowing forms are the everyday default.

Iterators are lazy

Here is the single most important fact about iterators, and the one beginners trip on. An iterator does nothing until something asks it for values. Building one is free and instant; it just sets up the machine. Look:

fn main() {
    let v = vec![1, 2, 3];
    let doubler = v.iter().map(|x| {
        println!("doubling {x}");
        x * 2
    });

    println!("iterator built, nothing has happened yet");
}

iterator built, nothing has happened yet

The map closure, which prints "doubling", never runs. map (the subject of the next lesson) doesn't double anything; it builds a new iterator that will double, when asked. Nothing asks here, so nothing happens. This is called laziness, and it's deliberate: it lets you chain many transformations together with no wasted work, because each value flows through the whole chain only when it's finally pulled out the end.

What pulls values out? A for loop does, or a method that consumes the iterator, like sum, count, or collect (lesson 19.5). Add one and the work happens:

fn main() {
    let v = vec![1, 2, 3];
    let doubled: Vec<i32> = v.iter().map(|x| {
        println!("doubling {x}");
        x * 2
    }).collect();

    println!("{doubled:?}");
}

doubling 1
doubling 2
doubling 3
[2, 4, 6]

Now collect drives the iterator, repeatedly calling next, which pulls each value through map, which runs the closure. Laziness is why "build a pipeline, then run it once at the end" is the natural shape of iterator code, and why an iterator with no consumer is almost always a bug the compiler will warn you about (unused must-use on the iterator).

Quiz time

Question #1

What is the one required method of the Iterator trait, and how does an iterator signal that it's finished?

Question #2

You have let v = vec![String::from("a"), String::from("b")]. What's the difference between v.iter(), v.iter_mut(), and v.into_iter()?

Question #3

What does this print, and why?

let nums = vec![1, 2, 3];
nums.iter().map(|x| println!("{x}"));
println!("done");

You now know what an iterator is and that it does nothing until driven. The next lesson (19.4) is the fun part: the adapters like map, filter, and zip that transform one iterator into another, building the pipelines laziness was designed for.