[Rust Guide] 13.5. Iterators - Definitions, the Iterator Trait, and the Next Method

13.5.0 Before We Begin

During its design, Rust drew inspiration from many languages, and functional programming had a particularly strong influence on Rust. Functional programming often includes passing functions as values to parameters, returning them from other functions, assigning them to variables for later execution, and so on.

In this chapter, we will discuss some Rust features that are similar to what many languages call functional features:

• Closures
• Iterators (this article)
• Improving the I/O Project with Closures and Iterators
• Performance of Closures and Iterators

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

13.5.1 What Is an Iterator

To talk about iterators, we first need to talk about the iterator pattern. The iterator pattern allows you to perform a task on each element in a sequence, one by one. In that process, the iterator is responsible for:

• Traversing each item
• Determining when the sequence has finished iterating

Rust iterators are lazy: unless you call a method that consumes the iterator, the iterator itself does nothing. In other words, if you write an iterator in your code but never use it, it is as if it did nothing at all.

Take a look at an example:

fn main() {
    let v1 = vec![1, 2, 3];
    let v1_iter = v1.iter();
}

v1 is a Vector, and v1.iter() creates an iterator for v1 and assigns it to v1_iter. But v1_iter is not used yet, so the iterator can be considered to have no effect.

Now let’s use the iterator to traverse the values:

fn main() {
    let v1 = vec![1, 2, 3];
    let v1_iter = v1.iter();
    for val in v1_iter {
        println!("Got: {}", val);
    }
}

This is equivalent to using each element in the iterator once in a loop.

13.5.2 The Iterator Trait

All iterators implement the Iterator trait. This trait is defined in the standard library and looks roughly like this:

pub trait Iterator {
    type Item;

    fn next(&mut self) -> Option<Self::Item>;

    // methods with default implementations elided
}

Two new pieces of syntax appear here: type Item and Self::Item. These syntax forms define types associated with the trait, and we will talk about that in a later article. For now, all you need to know is that implementing the Iterator trait requires you to define an Item type, and that type is used as the return type of next (the iterator’s return type).

The Iterator trait requires only one method: next. Each time next is called, it returns one item from the iterator, that is, one element of the sequence. Because the return type is Option, the result is wrapped in the Some variant. When iteration ends, None is returned.

In actual use, you can call next directly on the iterator. Take a look at an example:

#[cfg(test)]
mod tests {
    #[test]
    fn iterator_demonstration() {
        let v1 = vec![1, 2, 3];

        let mut v1_iter = v1.iter();

        assert_eq!(v1_iter.next(), Some(&1));
        assert_eq!(v1_iter.next(), Some(&2));
        assert_eq!(v1_iter.next(), Some(&3));
        assert_eq!(v1_iter.next(), None);
    }
}

• v1 is a Vector, and v1_iter is its iterator. Because the operations below are considered to change the iterator’s state, mut must be used to make it mutable.
• assert_eq!(v1_iter.next(), Some(&1)); is the first call to next, so it returns the first element in the Vector, wrapped in Some, which is Some(&1). It is &1 because the iterator’s return value is an immutable reference wrapped by Option.
• assert_eq!(v1_iter.next(), Some(&2)); is the second call to next, so it returns the second element in the Vector, wrapped in Some, which is Some(&2).
• And so on...
• Calling next on an iterator changes the iterator’s internal state that tracks its position in the sequence. In other words, each call consumes one element from the iterator. The for loop in the 13.5.1 example does not need mut because the for loop actually takes ownership of v1_iter.

13.5.3 Several Iteration Methods

The iter method we just used generates an iterator over immutable references, so the values obtained through next are actually immutable references to the elements in the Vector.

The into_iter method creates an iterator that takes ownership. In other words, as it iterates through the elements, it moves them into the new scope and takes ownership of them.

The iter_mut method uses mutable references when traversing values.