13.1 Introduction to Iterators

A Rust iterator is any construct that yields a sequence of elements, one at a time, without exposing the internal details of how those elements are accessed. This design balances safety and high performance, largely thanks to Rust’s zero-cost abstractions. Under the hood, iteration is driven by repeatedly calling next(), although you typically let for loops or iterator methods handle those calls for you.

Key Characteristics of Rust Iterators:

  • Abstraction: Iterators hide details of how elements are retrieved.
  • Lazy Evaluation: Transformations (known as ‘adapters’) do not perform work until a ‘consuming’ method is invoked.
  • Chainable Operations: Adapter methods like map() and filter() can be chained for concise, functional-style code.
  • Trait-Based: The Iterator trait provides a uniform interface for retrieving items, ensuring consistency across the language and standard library.
  • External Iteration: You explicitly call next() (directly or indirectly, e.g., via a for loop), which contrasts with internal iteration models found in some other languages.

13.1.1 The Iterator Trait

All iterators in Rust implement the Iterator trait:

#![allow(unused)]
fn main() {
pub trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
    // Additional methods with default implementations
}
}
  • Associated Type Item: The type of elements returned by the iterator.
  • Method next(): Returns Some(element) until the iterator is exhausted, then yields None thereafter.

While you can call next() manually, most iteration uses for loops or consuming methods that implicitly invoke next(). Once next() returns None, it must keep returning None on subsequent calls.

13.1.2 Mutable, Immutable, and Consuming Iteration

Rust offers three major approaches to iterating over collections, each granting a different kind of access:

  1. Immutable Iteration (iter())
    Borrows elements immutably:

    fn main() {
    let numbers = vec![1, 2, 3];
    for n in numbers.iter() {
        println!("{}", n);
    }
}
    • When to use: You only need read access to the elements.
    • Sugar: for n in &numbers is equivalent to for n in numbers.iter().

  2. Mutable Iteration (iter_mut())
    Borrows elements mutably:

    fn main() {
    let mut numbers = vec![1, 2, 3];
    for n in numbers.iter_mut() {
        *n += 1;
    }
    println!("{:?}", numbers); // [2, 3, 4]
}
    • When to use: You want to modify elements in-place.
    • Sugar: for n in &mut numbers is equivalent to for n in numbers.iter_mut().

  3. Consuming Iteration (into_iter())
    Takes full ownership of each element:

    fn main() {
    let numbers = vec![1, 2, 3];
    for n in numbers.into_iter() {
        println!("{}", n);
    }
    // `numbers` is no longer valid here
}
    • When to use: You don’t need the original collection after iteration.
    • Sugar: for n in numbers is equivalent to for n in numbers.into_iter().

13.1.3 The IntoIterator Trait

The for loop (for x in collection) relies on the IntoIterator trait, which defines how a type is converted into an iterator:

#![allow(unused)]
fn main() {
pub trait IntoIterator {
    type Item;
    type IntoIter: Iterator<Item = Self::Item>;

    fn into_iter(self) -> Self::IntoIter;
}
}

Standard collections all implement IntoIterator, so they work seamlessly with for loops. Notably, Vec<T> implements IntoIterator in three ways—by value, by reference, and by mutable reference—giving you control over ownership or borrowing.

13.1.4 Peculiarities of Iterator Adapters and References

When you chain methods like map() or filter(), the closures often operate on references. For example:

#![allow(unused)]
fn main() {
let numbers = vec![1, 2, 3];
let result: Vec<i32> = numbers.iter().map(|&x| x * 2).collect();
println!("{:?}", result); // [2, 4, 6]
}

Here, map() processes &x because .iter() borrows the elements. You might also see patterns like map(|x| (*x) * 2) or rely on Rust’s auto-dereferencing.

#![allow(unused)]
fn main() {
let numbers = [0, 1, 2];
let result: Vec<&i32> = numbers.iter().filter(|&&x| x > 1).collect();
println!("{:?}", result); // [2]
}

In the filter() above, you see &&x, an extra layer of reference due to the iter() mode. This might feel confusing initially, but it becomes second nature once you understand how iteration modes—immutable, mutable, or consuming—affect the closure’s input.

13.1.5 Standard Iterable Data Types

Most standard library types come with built-in iteration:

  • Vectors (Vec<T>): 
    #![allow(unused)]
fn main() {
let v = vec![1, 2, 3];
for x in v.iter() {
    println!("{}", x);
}
}
  • Arrays ([T; N]): 
    #![allow(unused)]
fn main() {
let arr = [10, 20, 30];
for x in arr.iter() {
    println!("{}", x);
}
}
  • Slices (&[T]): 
    #![allow(unused)]
fn main() {
let slice = &[100, 200, 300];
for x in slice.iter() {
    println!("{}", x);
}
}
  • HashMaps (HashMap<K, V>): 
    #![allow(unused)]
fn main() {
use std::collections::HashMap;
let mut map = HashMap::new();
map.insert("a", 1);
map.insert("b", 2);
for (key, value) in &map {
    println!("{}: {}", key, value);
}
}
  • Strings (String and &str): 
    #![allow(unused)]
fn main() {
let s = String::from("hello");
for c in s.chars() {
    println!("{}", c);
}
}
  • Ranges (Range, RangeInclusive): 
    #![allow(unused)]
fn main() {
for num in 1..5 {
    println!("{}", num);
}
}
  • Option (Option<T>): 
    #![allow(unused)]
fn main() {
let maybe_val = Some(42);
for val in maybe_val.iter() {
    println!("{}", val);
}
}

13.1.6 Iterators and Closures

Many iterator methods accept closures to specify how elements should be transformed or filtered:

  • Adapter Methods (e.g., map(), filter()) build new iterators but do not produce a final value immediately.
  • Consuming Methods (e.g., collect(), sum(), fold()) consume the iterator and yield a result.

Closures make your code concise and expressive without extra loops.

13.1.7 Basic Iterator Usage

A straightforward example is iterating over a vector with a for loop:

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];
    for number in numbers.iter() {
        print!("{} ", number);
    }
    // Output: 1 2 3 4 5
}

You can also chain multiple adapters for functional-style pipelines:

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];
    let processed: Vec<i32> = numbers
        .iter()
        .map(|x| x * 2)
        .filter(|&x| x > 5)
        .collect();
    println!("{:?}", processed); // [6, 8, 10]
}

13.1.8 Consuming vs. Non-Consuming Methods

  • Adapter (Non-Consuming) Methods: Return a new iterator (e.g., map(), filter(), take_while()), allowing further chaining.
  • Consuming Methods: Produce a final result or side effect (e.g., collect(), sum(), fold(), for_each()), after which the iterator is depleted and cannot be reused.