Chapter 13: Working with Iterators in Rust

Iterators are a cornerstone of idiomatic Rust programming, offering a powerful, safe, and efficient abstraction for processing sequences of data. For C programmers accustomed to manual pointer arithmetic and index tracking within loops (for (int i = 0; i < len; ++i), while (*ptr)), Rust’s iterators represent a significant shift. They allow you to express what you want to do with each element in a sequence, rather than focusing on the low-level mechanics of how to access it. This higher level of abstraction effectively prevents common C errors like off-by-one bugs, dereferencing invalid pointers, or iterator invalidation issues that arise when modifying a collection while iterating over it manually.

This chapter delves into using Rust’s built-in iterators, implementing custom iterators for your own data structures, and understanding how Rust achieves high performance through its zero-cost abstractions, often matching or exceeding the speed of equivalent C code.

13.1 The Essence of Rust Iterators

In programming, processing collections of items—arrays, lists, maps—is fundamental. Iteration is the process of accessing these items sequentially. While C uses explicit loops with index variables or pointers, Rust provides a more abstract and safer mechanism built around two core concepts: iterables and iterators.

Iterable: A type that can produce an iterator. Standard Rust collections (Vec<T>, HashMap<K, V>, String, arrays, slices) are iterable. They provide methods to create iterators over their contents. The IntoIterator trait formalizes this capability.
Iterator: An object responsible for managing the state of the iteration process. It implements the std::iter::Iterator trait, which defines a standard interface for producing a sequence of values. The fundamental method is next(), which attempts to yield the next item, returning Some(item) if available or None when the sequence is exhausted.

Rust collections offer several methods for iteration, each returning a specific iterator object that controls how elements are accessed:

iter(): Yields immutable references (&T). The collection is borrowed immutably.
iter_mut(): Yields mutable references (&mut T). The collection is borrowed mutably, allowing in-place modification.
into_iter(): Consumes the collection and yields elements by value (T). Ownership is transferred out of the collection.

Rust’s for loop seamlessly integrates with this system. It implicitly calls into_iter() on the expression being looped over and then repeatedly calls next() on the resulting iterator until it returns None.

This separation of concerns—the collection holding the data and the iterator managing the traversal—leads to cleaner, more maintainable code.

Fundamental Concepts:

Abstraction: Iterators decouple sequence processing logic from the underlying data source (vector, hash map, file lines, number range). The same iterator methods (map, filter, collect) work on any sequence produced by an iterator.
Laziness: Many iterator operations, known as adapters (map, filter), do not execute immediately. They return a new iterator representing the transformation. Computation is deferred until a consuming method (collect, sum, for_each) is called, which pulls items through the iterator chain. This avoids unnecessary work.
Composability: Iterators can be chained together elegantly, enabling complex data processing pipelines expressed concisely, often in a functional style (e.g., data.iter().filter(...).map(...).sum()).
Safety: Combined with Rust’s ownership and borrowing rules, iterators provide strong compile-time guarantees against common C pitfalls like dangling pointers or modifying a collection while iterating over it (unless using iter_mut explicitly and safely).
Performance (Zero-Cost Abstraction): Rust’s compiler heavily optimizes iterator chains, often generating machine code equivalent to handwritten C loops. This makes iterators an efficient choice even for performance-critical code.

13.1.1 The `Iterator` Trait

The foundation of Rust’s iteration mechanism is the Iterator trait:

#![allow(unused)]
fn main() {
pub trait Iterator {
    // The type of element produced by the iterator.
    type Item;

    // Advances the iterator and returns the next value.
    // Returns `Some(Item)` if a value is available.
    // Returns `None` when the sequence is exhausted.
    // Takes `&mut self` because advancing typically modifies
    // the iterator's internal state.
    fn next(&mut self) -> Option<Self::Item>;

    // Provides numerous other methods (adapters and consumers)
    // with default implementations that utilize `next()`.
    // Examples: map, filter, fold, sum, collect, etc.
}
}

Item Associated Type: Defines the type of value yielded by the iterator (e.g., i32, &String, Result<String, io::Error>).
next() Method: The sole required method. It must advance the iterator’s internal state and return the next item wrapped in Some. Once the sequence ends, it must consistently return None. (This “always None after first None” behavior is formalized by the FusedIterator trait, implemented by most standard iterators).

While you can manually call next() (e.g., while let Some(item) = my_iterator.next() { ... }), idiomatic Rust overwhelmingly favors using for loops or iterator consumer methods, which handle the next() calls implicitly and more readably.

13.1.2 The `IntoIterator` Trait and `for` Loops

Now that we’ve seen what the Iterator trait requires, how do we typically get an iterator object from a collection like a Vec? This is the role of the IntoIterator trait, which is fundamental to how Rust’s for loop operates.

Rust’s for loop is syntactic sugar built upon the IntoIterator trait:

#![allow(unused)]
fn main() {
pub trait IntoIterator {
    // The type of element yielded by the resulting iterator.
    type Item;
    // The specific iterator type returned by `into_iter`.
    type IntoIter: Iterator<Item = Self::Item>;

    // Consumes `self` (or borrows it) to create an iterator.
    fn into_iter(self) -> Self::IntoIter;
}
}

When you write for item in expression, Rust implicitly calls expression.into_iter(). This method returns an actual Iterator, which the for loop then drives by repeatedly calling next() until it receives None.

Standard collections implement IntoIterator in multiple ways (for the collection type itself, for &collection, and for &mut collection) to support the different iteration modes based on ownership and borrowing.

13.1.3 Iteration Modes: `iter()`, `iter_mut()`, `into_iter()`

Most collections provide three common ways to obtain an iterator, reflecting different needs regarding data access and ownership. These are typically exposed via inherent methods (iter, iter_mut, into_iter) and are also triggered implicitly by for loops based on how the collection is referenced:

Immutable Iteration (iter() / &collection)

Yields immutable references (&T).
The original collection is borrowed immutably; it remains accessible after the loop.
Method: .iter()
for loop syntax: for item_ref in &collection { ... } (equivalent to for item_ref in collection.iter() { ... })

fn main() {
    let data = vec!["alpha", "beta", "gamma"];

    // Using the method explicitly: yields &&str
    println!("Using data.iter():");
    for item_ref in data.iter() {
        // item_ref has type &&str
        // println! can format &&str directly because it implements Display
        println!(" - Item: {}", item_ref);
    }

    // Using the for loop sugar with &data: also yields &&str
    println!("Using &data:");
    for item_ref in &data {
        // item_ref also has type &&str
         println!(" - Item: {}", item_ref);
    }

    // data is still valid and usable here
    println!("Original data: {:?}", data);
}

Mutable Iteration (iter_mut() / &mut collection)

Yields mutable references (&mut T).
Allows modifying the collection’s elements in place.
The original collection is borrowed mutably. Cannot be accessed immutably elsewhere during the loop.
Method: .iter_mut()
for loop syntax: for item_mut_ref in &mut collection { ... } (equivalent to for item_mut_ref in collection.iter_mut() { ... })

fn main() {
    let mut numbers = vec![10, 20, 30];
    // Using the method explicitly:
    for num_ref in numbers.iter_mut() {
        // num_ref has type &mut i32
        *num_ref += 5; // Dereference (*) to modify the value
    }
    println!("Modified numbers: {:?}", numbers); // Output: [15, 25, 35]

    // Using the for loop sugar:
    for num_ref in &mut numbers {
        // num_ref also has type &mut i32
         *num_ref *= 2;
    }
    println!("Doubled numbers: {:?}", numbers); // Output: [30, 50, 70]
}

Consuming Iteration (into_iter() / collection)

Yields owned values (T).
Takes ownership of (consumes) the collection. The original collection variable cannot be used after the for statement, as ownership is moved to the iterator created by into_iter(). The elements themselves are moved out of the collection one by one.
Method: .into_iter()
for loop syntax: for item in collection { ... } (equivalent to for item in collection.into_iter() { ... })

fn main() {
    // --- Using the for loop sugar (most common) ---
    let strings1 = vec![String::from("hello"), String::from("world")];
    let mut lengths1 = Vec::new();
    println!("Using `for s in strings` (sugar):");
    // This implicitly calls strings1.into_iter()
    for s in strings1 { // `strings1` is moved here
         // s has type String (owned value, not Copy)
         println!(" - Got owned string: '{}'", s);
         lengths1.push(s.len());
         // s goes out of scope and is dropped here
    }
    // println!("{:?}", strings1); // Error! `strings1` value was moved
    println!("   Lengths: {:?}", lengths1); // Output: [5, 5]

    // --- Using the method explicitly ---
    let strings2 = vec![String::from("hello"), String::from("world")];
    let mut lengths2 = Vec::new();
    println!("\nUsing `for s in strings.into_iter()` (explicit):");
    // This explicitly calls strings2.into_iter()
    for s in strings2.into_iter() { // `strings2` is moved here
         // s also has type String (owned value)
         println!(" - Got owned string: '{}'", s);
         lengths2.push(s.len());
         // s goes out of scope and is dropped here
    }
    // println!("{:?}", strings2); // Error! `strings2` value was moved
    println!("   Lengths: {:?}", lengths2); // Output: [5, 5]
}

Note on Vec<String> vs. Vec<&str>: This example uses Vec<String> deliberately. The goal is to illustrate consuming iteration where owned values (String), which are not Copy, are moved out of the collection. If we had used let strings = vec!["hello", "world"]; (creating a Vec<&str>), the loop for s in strings would still consume the vector, but s inside the loop would be of type &str. Since &str is Copy, the ownership transfer aspect for the elements wouldn’t be as apparent as it is with the non-Copy String type.

It’s a strong convention in Rust to provide these inherent methods (.iter(), .iter_mut(), and a consuming .into_iter(self)) on collection-like types, even though the for loop can work directly with references via the IntoIterator trait implementations. These methods improve discoverability and allow for explicit iterator creation when needed (e.g., for chaining methods before a loop). Typically, their implementation is straightforward: the inherent iter(&self) method simply calls IntoIterator::into_iter on self (which has type &Collection), and similarly for iter_mut and the consuming into_iter.

Choosing the Correct Mode:

Use iter() (&collection) for read-only access when you need the collection afterward.
Use iter_mut() (&mut collection) when you need to modify elements in place.
Use into_iter() (collection) when you want to transfer ownership of the elements out of the collection (e.g., into a new collection or thread, or to consume them).

13.1.4 Understanding References in Closures (`&x`, `&&x`)

When using iterator adapters like map or filter with iter(), the closures often receive references to the items yielded by the iterator. This can sometimes lead to double references (&&T). This occurs naturally:

some_collection.iter() produces an iterator yielding items of type &T.
Adapters like filter pass a reference to the yielded item into the closure. The closure therefore receives a parameter of type &(&T), which simplifies to &&T.

Rust’s pattern matching in closures often handles this gracefully, allowing you to directly access the underlying value:

fn main() {
    let numbers = vec![1, 2, 3, 4];

    // `numbers.iter()` yields `&i32`.
    // `filter`'s closure receives `&(&i32)`, i.e., `&&i32`.

    // Using pattern matching `|&&x|` to automatically dereference twice:
    let evens_refs: Vec<&i32> = numbers.iter()
        .filter(|&&x| x % 2 == 0) // `x` here is `i32` due to pattern matching
        .collect();
    println!("Evens (refs): {:?}", evens_refs); // Output: [&2, &4]

    // If we need owned values, we can copy *after* filtering:
    // Note: `copied()` works because i32 implements the `Copy` trait.
    // For non-`Copy` types, use `.cloned()` if `T` implements `Clone`.
    let evens_owned: Vec<i32> = numbers.iter()
        .filter(|&&x| x % 2 == 0)
        .copied() // Converts the `&i32` yielded by filter into `i32`
        .collect();
    println!("Evens (owned): {:?}", evens_owned); // Output: [2, 4]

    // Alternatively, dereference explicitly inside the closure:
    let odds: Vec<i32> = numbers.iter()
        .filter(|item_ref_ref| (**item_ref_ref) % 2 != 0) // **item_ref_ref gives i32
        .copied() // Convert &i32 to i32
        .collect();
    println!("Odds (owned): {:?}", odds); // Output: [1, 3]

    // Using `into_iter()` avoids the extra reference layer if ownership is intended:
    let squares: Vec<i32> = numbers.into_iter() // yields `i32` directly
        .map(|x| x * x) // closure receives `i32` directly
        .collect();
    println!("Squares: {:?}", squares); // Output: [1, 4, 9, 16]
    // `numbers` is no longer available here
}

Understanding the iteration mode (iter, iter_mut, into_iter) tells you the base type yielded (&T, &mut T, or T), which helps predict the types received by closures in subsequent adapters and whether dereferencing or methods like copied/cloned are needed.

13.1.5 Iterator Adapters vs. Consumers

Iterator methods fall into two main categories:

Adapters (Lazy): These transform an iterator into a new iterator with different behavior (e.g., map, filter, take, skip, enumerate, zip, chain, peekable, cloned, copied). They perform no work until the iterator is consumed. They are chainable, building up a processing pipeline.
Consumers (Eager): These consume the iterator, driving the next() calls and producing a final result or side effect (e.g., collect, sum, product, fold, for_each, count, last, nth, any, all, find, position). Once a consumer is called, the iterator (and the chain built upon it) is used up and cannot be used again.

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];

    // Adapters: map and filter (lazy, no computation happens yet)
    // numbers.iter() -> yields &i32
    // .map(|&x| x * 10) -> yields i32 (deref pattern `|&x|`)
    // .filter(|&val| val > 25) -> `val` is `i32` here
    let adapter_chain = numbers.iter()
        .map(|&x| x * 10) // Needs `Copy` or manual deref `*x * 10`
        .filter(|&val| val > 25);

    // Consumer: collect (eager, executes the chain)
    // `collect` gathers the i32 values yielded by filter into a Vec<i32>.
    let result: Vec<i32> = adapter_chain.collect();

    println!("Result: {:?}", result); // Output: [30, 40, 50]

    // Trying to use adapter_chain again would fail compilation:
    // let count = adapter_chain.count(); // Error: use of moved value `adapter_chain`
}

13.2 Common Iterator Methods

The Iterator trait provides a rich set of default methods built upon the fundamental next() method.

13.2.1 Adapters (Lazy Methods Returning Iterators)

map(closure): Applies closure to each element, creating an iterator of the results. Signature: |Self::Item| -> OutputType.
```
#![allow(unused)]
fn main() {
let squares: Vec<_> = vec![1, 2, 3].iter().map(|&x| x * x).collect(); // [1, 4, 9]
}
```

filter(predicate): Creates an iterator yielding only elements for which the predicate closure returns true. Signature: |&Self::Item| -> bool.

#![allow(unused)]
fn main() {
let evens: Vec<_> = vec![1, 2, 3, 4].iter().filter(|&&x| x % 2 == 0).copied()
    .collect(); // [2, 4]
}

filter_map(closure): Filters and maps simultaneously. The closure returns an Option<OutputType>. Only Some(value) results are yielded (unwrapped). Signature: |Self::Item| -> Option<Output>. Ideal for parsing or fallible transformations.
```
#![allow(unused)]
fn main() {
let nums_str = ["1", "two", "3", "four"];
let nums: Vec<i32> = nums_str.iter().filter_map(|s| s.parse().ok()).collect();
// [1, 3]
}
```

enumerate(): Wraps the iterator to yield (index, element) pairs, starting at index 0.

fn main() {
let items = vec!["a", "b"];
for (i, item) in items.iter().enumerate() {
    println!("{}: {}", i, *item); // Output: 0: a, 1: b
}
}

peekable(): Creates an iterator allowing inspection of the next element via .peek() without consuming it from the underlying iterator. Useful for lookahead.
take(n): Yields at most the first n elements.
skip(n): Skips the first n elements, then yields the rest.
take_while(predicate): Yields elements while predicate returns true. Stops permanently once predicate returns false.
skip_while(predicate): Skips elements while predicate returns true. Yields all subsequent elements (including the one that first returned false).
step_by(step): Creates an iterator yielding every step-th element (e.g., 0th, step-th, 2*step-th, …).

zip(other_iterator): Combines two iterators into a single iterator of pairs (a, b). Stops when the shorter iterator is exhausted.

#![allow(unused)]
fn main() {
let nums = [1, 2];
let letters = ['a', 'b', 'c'];
let pairs: Vec<_> = nums.iter().zip(letters.iter()).collect();
// [(&1, &'a'), (&2, &'b')]
}

chain(other_iterator): Yields all elements from the first iterator, then all elements from the second. Both iterators must yield the same Item type.

#![allow(unused)]
fn main() {
let v1 = [1, 2];
let v2 = [3, 4];
let combined: Vec<_> = v1.iter().chain(v2.iter()).copied().collect();
// [1, 2, 3, 4]
}

cloned(): Converts an iterator yielding &T into one yielding T by calling clone() on each element. Requires T: Clone.
copied(): Converts an iterator yielding &T into one yielding T by bitwise copying the value. Requires T: Copy. Generally preferred over cloned() for Copy types for efficiency.
rev(): Reverses the direction of an iterator. Requires the iterator to implement DoubleEndedIterator.

13.2.2 Consumers (Eager Methods Consuming the Iterator)

collect() / collect::<CollectionType>(): Consumes the iterator, gathering elements into a specified collection (e.g., Vec<T>, HashMap<K, V>, String, Result<Vec<T>, E>). Type inference often works, but sometimes explicit type annotation (::<Type>) is needed.
```
#![allow(unused)]
fn main() {
let doubled: Vec<i32> = vec![1, 2].iter().map(|&x| x * 2).collect();
let chars: String = ['h', 'i'].iter().collect();
}
```
for_each(closure): Consumes the iterator, calling closure for each element. Used for side effects (like printing). Signature: |Self::Item|.
```
#![allow(unused)]
fn main() {
vec![1, 2].iter().for_each(|x| println!("{}", x));
}
```
sum() / product(): Consumes the iterator, computing the sum or product. Requires Item to implement std::iter::Sum<Self::Item> or std::iter::Product<Self::Item>, respectively.
```
#![allow(unused)]
fn main() {
let total: i32 = vec![1, 2, 3].iter().sum(); // 6
let factorial: i64 = (1..=5).product(); // 120
}
```
fold(initial_value, closure): Consumes the iterator, applying an accumulator function. closure takes (accumulator, element) and returns the new accumulator value. Powerful for custom aggregations. Signature: (Accumulator, Self::Item) -> Accumulator.
```
#![allow(unused)]
fn main() {
let product = vec![1, 2, 3].iter().fold(1, |acc, &x| acc * x); // 6
}
```
reduce(closure): Similar to fold, but uses the first element as the initial accumulator. Returns Option<Self::Item> (None if the iterator is empty). Signature: (Self::Item, Self::Item) -> Self::Item.
count(): Consumes the iterator and returns the total number of items yielded (usize).
last(): Consumes the iterator and returns the last element as an Option<Self::Item>.
nth(n): Consumes the iterator up to and including the n-th element (0-indexed) and returns it as Option<Self::Item>. Consumes all prior elements. Efficient for ExactSizeIterator.
any(predicate): Consumes the iterator, returning true if any element satisfies predicate. Short-circuits (stops early if true is found). Signature: |Self::Item| -> bool.
all(predicate): Consumes the iterator, returning true if all elements satisfy predicate. Short-circuits (stops early if false is found). Signature: |Self::Item| -> bool.
find(predicate): Consumes the iterator, returning the first element satisfying predicate as an Option<Self::Item>. Short-circuits. Signature: |&Self::Item| -> bool.
```
#![allow(unused)]
fn main() {
let nums = [1, 2, 3, 4];
let first_even: Option<&i32> = nums.iter().find(|&&x| x % 2 == 0); // Some(&2)
}
```
find_map(closure): Consumes the iterator, applying closure to each element. Returns the first non-None result produced by the closure. Signature: |Self::Item| -> Option<ResultType>. Short-circuits.
position(predicate): Consumes the iterator, returning the index (usize) of the first element satisfying predicate as Option<usize>. Short-circuits. Signature: |Self::Item| -> bool.

13.3 Creating Custom Iterators

While standard library iterators cover many use cases, you’ll often need to make your own data structures iterable. When creating custom iterators, there are generally two structural approaches:

The Type is the Iterator: For simple cases, the type itself can hold the necessary iteration state (like a current index or value) and directly implement the Iterator trait, including the next() method. Instances of this type can then be used directly in loops or iterator chains. We will see this pattern with a Counter example.
The Type Produces an Iterator: More commonly, especially for types acting as collections, the type itself doesn’t implement Iterator. Instead, it implements the IntoIterator trait. Its into_iter() method constructs and returns a separate iterator struct (which holds the iteration state and implements Iterator with the next() logic). This is the pattern used by standard collections like Vec and the one we’ll initially demonstrate for a custom Pixel struct.

A key benefit of implementing the Iterator trait (either directly on your type or on a separate iterator struct) is that you automatically gain access to a wide array of powerful adapter and consumer methods defined directly on the trait itself (like map, filter, fold, sum, collect, and many others shown in Section 13.2). These methods have default implementations written in terms of the required next() method. Therefore, by simply providing the core next() logic for your specific type, you enable users to immediately leverage the entire rich ecosystem of standard iterator operations on your custom iterator, just like they would with standard library iterators.

Let’s illustrate these approaches with examples.

13.3.1 Example 1: Iterating Over Struct Fields (Manual Implementation)

This approach follows the second pattern mentioned above: the Pixel struct implements IntoIterator to produce separate iterator structs (PixelIter, PixelIterMut, etc.) which implement Iterator. This is general but can involve boilerplate code.

#[derive(Debug, Clone, Copy)] // Added derives for easier use later
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
}

// --- Consuming Iterator (Yields owned u8) ---

struct PixelIntoIterator {
    pixel: Pixel, // Owns the pixel data
    index: u8,    // State: which component is next (0=r, 1=g, 2=b)
}

impl Iterator for PixelIntoIterator {
    type Item = u8; // Yields owned u8 values

    fn next(&mut self) -> Option<Self::Item> {
        let result = match self.index {
            0 => Some(self.pixel.r),
            1 => Some(self.pixel.g),
            2 => Some(self.pixel.b),
            _ => None, // Sequence exhausted
        };
        self.index = self.index.wrapping_add(1); // Use wrapping_add for safety
        result
    }
}

// Implement IntoIterator for Pixel to enable `for val in pixel`
impl IntoIterator for Pixel {
    type Item = u8;
    type IntoIter = PixelIntoIterator;

    fn into_iter(self) -> Self::IntoIter {
        PixelIntoIterator { pixel: self, index: 0 }
    }
}

// --- Immutable Reference Iterator (Yields &u8) ---

// Lifetime 'a ensures the iterator doesn't outlive the borrowed Pixel
struct PixelIter<'a> {
    pixel: &'a Pixel, // Holds an immutable reference
    index: u8,
}

impl<'a> Iterator for PixelIter<'a> {
    type Item = &'a u8; // Yields immutable references

    fn next(&mut self) -> Option<Self::Item> {
        let result = match self.index {
            0 => Some(&self.pixel.r),
            1 => Some(&self.pixel.g),
            2 => Some(&self.pixel.b),
            _ => None,
        };
        self.index = self.index.wrapping_add(1);
        result
    }
}

// Implement IntoIterator for &Pixel to enable `for val_ref in &pixel`
impl<'a> IntoIterator for &'a Pixel {
    type Item = &'a u8;
    type IntoIter = PixelIter<'a>;

    fn into_iter(self) -> Self::IntoIter {
        PixelIter { pixel: self, index: 0 }
    }
}

// --- Mutable Reference Iterator (Yields &mut u8) ---

struct PixelIterMut<'a> {
    pixel: &'a mut Pixel, // Holds a mutable reference
    index: u8,
}

impl<'a> Iterator for PixelIterMut<'a> {
    type Item = &'a mut u8; // Yields mutable references

    // Returning mutable references from `next` when iterating over mutable
    // fields of a struct borrowed mutably can be tricky for the borrow checker.
    // Using raw pointers temporarily inside `next` is one pattern to handle this,
    // though it requires `unsafe`. It bypasses the borrow checker's static
    // analysis for this specific, localized operation, relying on the programmer
    // to ensure safety (which holds here as we access distinct fields per index).
    fn next(&mut self) -> Option<Self::Item> {
        let pixel_ptr: *mut Pixel = self.pixel; // Get raw pointer to the mutable pixel
        let result = match self.index {
          // Safety: `pixel_ptr` is valid, and index ensures we access distinct fields
          // mutably within the lifetime 'a.
            0 => Some(unsafe { &mut (*pixel_ptr).r }),
            1 => Some(unsafe { &mut (*pixel_ptr).g }),
            2 => Some(unsafe { &mut (*pixel_ptr).b }),
            _ => None,
        };
        self.index = self.index.wrapping_add(1);
        result
    }
}

// Implement IntoIterator for &mut Pixel to enable `for val_mut in &mut pixel`
impl<'a> IntoIterator for &'a mut Pixel {
    type Item = &'a mut u8;
    type IntoIter = PixelIterMut<'a>;

    fn into_iter(self) -> Self::IntoIter {
        PixelIterMut { pixel: self, index: 0 }
    }
}

// Optional: Add convenience methods like standard collections
impl Pixel {
    fn iter(&self) -> PixelIter<'_> {
        self.into_iter() // Equivalent to (&*self).into_iter()
    }

    fn iter_mut(&mut self) -> PixelIterMut<'_> {
        self.into_iter() // Equivalent to (&mut *self).into_iter()
    }
}

fn main() {
    let pixel1 = Pixel { r: 255, g: 0, b: 128 };

    println!("Iterating by value (consumes pixel1):");
    // Note: pixel1 cannot be used after this loop because it's moved
    for val in pixel1 {
        println!(" - Value: {}", val);
    }
    // println!("{:?}", pixel1); // Error: use of moved value

    let pixel2 = Pixel { r: 10, g: 20, b: 30 };
    println!("\nIterating by immutable reference:");
    for val_ref in pixel2.iter() { // or `for val_ref in &pixel2`
        println!(" - Ref: {}", val_ref); // *val_ref is u8
    }
    println!("Pixel 2 after iter: {:?}", pixel2); // pixel2 is still usable

    let mut pixel3 = Pixel { r: 100, g: 150, b: 200 };
    println!("\nIterating by mutable reference:");
    for val_mut in pixel3.iter_mut() { // or `for val_mut in &mut pixel3`
        *val_mut = val_mut.saturating_add(10); // Modify value safely
        println!(" - Mut Ref: {}", *val_mut);
    }
    println!("Pixel 3 after iter_mut: {:?}", pixel3);

    let pixel4 = Pixel { r: 2, g: 3, b: 4 };
    // Using methods inherited from the Iterator trait:
    let sum: u16 = pixel4.iter().map(|&v| v as u16).sum();
    println!("\nSum using iter(): {}", sum); // Output: 9

    let product: u32 = pixel4.into_iter().map(|v| v as u32).product();
    println!("Product using into_iter(): {}", product); // Output: 24
    // pixel4 is consumed here
}

Key points from this example:

Separate iterator structs (PixelIntoIterator, PixelIter, PixelIterMut) manage state and hold either owned data, an immutable reference, or a mutable reference.
Implementing IntoIterator for Pixel, &Pixel, and &mut Pixel makes the struct work seamlessly with for loops in all three modes.
Lifetimes ('a) are crucial for the reference iterators.
The unsafe block in PixelIterMut::next demonstrates a pattern sometimes needed to safely return mutable references to different fields across calls, bypassing borrow checker limitations within the method body.
Crucially, even though we only implemented next(), we could still call .map() and .sum() or .product() because those methods are provided by the Iterator trait itself.

13.3.2 Example 2: A Simple Self-Contained Iterator (`Counter`)

Sometimes, the iterator is the primary object, holding its own state directly, rather than iterating over a separate collection. This follows the first structural pattern mentioned earlier: the type implements Iterator directly.

// An iterator that counts from 'start' up to 'end' (inclusive).
struct Counter {
    current: u32,
    end: u32,
}

impl Counter {
    fn new(start: u32, end: u32) -> Self {
        Counter { current: start, end }
    }
}

impl Iterator for Counter {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        if self.current <= self.end {
            let value = self.current;
            // Use saturating_add for safety against overflow, though unlikely here
            self.current = self.current.saturating_add(1);
            Some(value)
        } else {
            None // Signal the end of the iteration
        }
    }
}

fn main() {
    println!("Counting from 1 to 5:");
    // The Counter struct itself implements Iterator
    let counter1 = Counter::new(1, 5);
    for count in counter1 { // `for` loop works directly on an Iterator
        println!(" - {}", count);
    }

    // Iterator methods like `sum` can be called directly on Counter
    // because it implements Iterator.
    let sum_of_range: u32 = Counter::new(10, 15).sum();
    println!("\nSum of range 10 to 15: {}", sum_of_range); // 10+..+15 = 75

    let mut counter2 = Counter::new(1, 3);
    assert_eq!(counter2.next(), Some(1));
    assert_eq!(counter2.next(), Some(2));
    assert_eq!(counter2.next(), Some(3));
    assert_eq!(counter2.next(), None);
    assert_eq!(counter2.next(), None); // Should remain None (FusedIterator behavior)
}

In this Counter example, we didn’t need IntoIterator. Why?

The Counter struct itself implements the Iterator trait. It holds its own state (current, end).
The for loop and methods like sum() are designed to work with any type that implements Iterator. If the type passed to them already is an iterator (like our counter1 variable), they use it directly.
If, however, the type used in a for loop (like a Vec or our Pixel struct) is not an iterator itself, the loop requires that type to implement the IntoIterator trait. The loop then implicitly calls the .into_iter() method on that type to obtain the actual iterator it needs.
Therefore, IntoIterator is primarily needed to define how to get an iterator from another type (like a collection). Since Counter is already the iterator, this step isn’t required for it.

13.3.3 Leveraging Array Iterators via Delegation

The manual implementation for Pixel in the first example works, but involves significant boilerplate code. If the data within your struct can be logically represented as a standard collection type, like an array or a slice, you can often simplify the implementation significantly by delegating to the standard library’s existing, optimized iterators.

This approach involves:

Storing the data internally in a standard collection (like an array).
Implementing IntoIterator for your type (and its references) by calling the corresponding into_iter(), .iter(), or .iter_mut() methods on the internal collection.

Let’s revise the Pixel struct to hold its components in an internal array [u8; 3] and see how this simplifies the iterator implementations.

use std::slice::{Iter, IterMut}; // Import slice iterators for type annotations

#[derive(Debug, Clone, Copy)]
struct PixelArray {
    // Store components in an array
    channels: [u8; 3], // [r, g, b]
}

impl PixelArray {
    fn new(r: u8, g: u8, b: u8) -> Self {
        PixelArray { channels: [r, g, b] }
    }

    // Convenience accessors (optional but helpful)
    fn r(&self) -> u8 { self.channels[0] }
    fn g(&self) -> u8 { self.channels[1] }
    fn b(&self) -> u8 { self.channels[2] }
}

// Implement IntoIterator for PixelArray (consuming iteration)
// This delegates to the array's consuming iterator.
impl IntoIterator for PixelArray {
    type Item = u8;
    // Delegate to the array's consuming iterator type: `std::array::IntoIter`
    type IntoIter = std::array::IntoIter<u8, 3>;

    fn into_iter(self) -> Self::IntoIter {
        // Arrays implement IntoIterator, so we just call it on the internal array
        self.channels.into_iter()
    }
}

// --- We DO need explicit impl IntoIterator for &PixelArray ---
// To enable `for item in &my_pixel_array`, we must implement `IntoIterator`
// for the reference type `&PixelArray`. We achieve this easily by
// delegating to the `.iter()` method of the internal `channels` array,
// which returns an iterator yielding `&u8`.
impl<'a> IntoIterator for &'a PixelArray {
    type Item = &'a u8;
    // The iterator type yielded by `.iter()` on an array/slice is `std::slice::Iter`
    type IntoIter = Iter<'a, u8>;

    fn into_iter(self) -> Self::IntoIter {
        // Call `.iter()` on the internal array
        self.channels.iter()
    }
}

// --- We DO need explicit impl IntoIterator for &mut PixelArray ---
// Similarly, to enable `for item in &mut my_pixel_array`, we implement
// `IntoIterator` for `&mut PixelArray`. This implementation delegates
// to the internal array's `.iter_mut()` method, which returns an
// iterator yielding `&mut u8`.
impl<'a> IntoIterator for &'a mut PixelArray {
    type Item = &'a mut u8;
     // The type yielded by `.iter_mut()` on an array/slice is `std::slice::IterMut`
    type IntoIter = IterMut<'a, u8>;

    fn into_iter(self) -> Self::IntoIter {
         // Call `.iter_mut()` on the internal array
        self.channels.iter_mut()
    }
}

// By providing these implementations, we correctly leverage the standard
// library's efficient slice iterators (`slice::Iter` and `slice::IterMut`)
// for our custom type, without needing to rewrite the iteration logic itself.

// Optional convenience methods (often added for discoverability, mirroring std lib)
impl PixelArray {
    pub fn iter(&self) -> Iter<'_, u8> {
        self.channels.iter() // Delegate directly
    }

    pub fn iter_mut(&mut self) -> IterMut<'_, u8> {
        self.channels.iter_mut() // Delegate directly
    }
}

fn main() {
    let pixel = PixelArray::new(255, 0, 128);

    println!("Iterating by value (consuming):");
    // `for val in pixel` calls `pixel.into_iter()`
    for val in pixel {
        println!(" - Value: {}", val);
    }
    // pixel is consumed here

    let pixel_ref = PixelArray::new(10, 20, 30);
    println!("\nIterating by immutable ref. (via impl IntoIterator for &PixelArray):");
    // `for val_ref in &pixel_ref` now correctly calls `(&pixel_ref).into_iter()`
    for val_ref in &pixel_ref { // This now works
        println!(" - Ref: {}", val_ref); // val_ref is &u8
    }
     // Example using the convenience method explicitly:
    // for val_ref in pixel_ref.iter() { println!(" - Ref: {}", val_ref); }

    let mut pixel_mut = PixelArray::new(100, 150, 200);
    println!("\nIterating by mutable r. (via impl IntoIterator for &mut PixelArray):");
    // `for val_mut in &mut pixel_mut` now correct calls `(&mut pixel_mut).into_iter()`
    for val_mut in &mut pixel_mut { // This now works
        *val_mut = val_mut.saturating_sub(10); // Modify
        println!(" - Mut Ref: {}", *val_mut); // val_mut is &mut u8
    }
    println!("Pixel after mut iteration: {:?}", pixel_mut);
    // Example using the convenience method explicitly:
    // for val_mut in pixel_mut.iter_mut() { *val_mut += 5;
    // println!(" - Mut Ref: {}", *val_mut); }

    // We can still use map, sum etc. because the iterators produced
    // (`std::array::IntoIter`, `slice::Iter`, `slice::IterMut`) implement Iterator.
    let pixel_sum = PixelArray::new(5, 6, 7);
    let sum: u16 = pixel_sum.iter().map(|&v| v as u16).sum();
     println!("\nSum using iter() on PixelArray: {}", sum); // Output: 18
}

This section demonstrates how to make a struct iterable in all three modes by containing a standard collection (an array in this case) and implementing the necessary IntoIterator traits via simple delegation. This is often much less work and less error-prone than implementing the next() logic manually, while also benefiting from the performance of the standard library’s iterators.

13.4 Advanced Iterator Traits

Beyond the base Iterator trait, several others provide additional capabilities and enable optimizations:

DoubleEndedIterator: For iterators that can efficiently yield elements from both the front (next()) and the back (next_back()). Enables methods like rev(). Implemented by iterators over slices, VecDeque, ranges, etc.

fn main() {
    let numbers = vec![1, 2, 3, 4, 5];
    let mut iter = numbers.iter(); // slice::Iter implements DoubleEndedIterator

    assert_eq!(iter.next(), Some(&1));      // Consume from front
    assert_eq!(iter.next_back(), Some(&5)); // Consume from back
    assert_eq!(iter.next(), Some(&2));
    assert_eq!(iter.next_back(), Some(&4));
    // Remaining elements are [&3].
    let remaining: Vec<&i32> = iter.collect();
    assert_eq!(remaining, vec![&3]);

    // Use rev() on a double-ended iterator
    let reversed: Vec<&i32> = numbers.iter().rev().collect();
    assert_eq!(reversed, vec![&5, &4, &3, &2, &1]);
}

ExactSizeIterator: For iterators that know precisely how many elements remain. Provides len() method returning the exact count. Allows consumers like collect() to potentially pre-allocate capacity, improving performance. Implemented by iterators over slices, arrays, Vec, VecDeque, simple ranges, etc. Note: Adapters like filter or flat_map typically produce iterators that are not ExactSizeIterator, as the final count isn’t known without iterating through them.

fn main() {
    let numbers = vec![10, 20, 30, 40];
    let mut iter = numbers.iter(); // slice::Iter implements ExactSizeIterator
    assert_eq!(iter.len(), 4);
    iter.next();
    assert_eq!(iter.len(), 3);

    // A filtered iterator does not know its exact size in advance
    let filtered_iter = numbers.iter().filter(|&&x| x > 15);
    // The following line would cause a compile error:
    // assert_eq!(filtered_iter.len(), 3); // Error: no method named `len` found

    // However, ALL iterators provide `size_hint()`
    // size_hint() returns (lower_bound, Option<upper_bound>)
    assert_eq!(filtered_iter.size_hint(), (0, Some(4))); // May be 0 to 4 elements

    let collected: Vec<_> = filtered_iter.collect(); // Iteration happens here
    assert_eq!(collected.len(), 3); // Actual count after iteration
}

size_hint(): A method available on all iterators via the Iterator trait. Returns a tuple (lower_bound, Option<upper_bound>) estimating the number of remaining elements. The lower bound is guaranteed to be accurate. For ExactSizeIterator, lower_bound == upper_bound.unwrap(), and len() is simply a convenience method for this. size_hint is used internally by methods like collect to make initial capacity reservations.
FusedIterator: A marker trait indicating that once the iterator returns None, all subsequent calls to next() (and next_back() if applicable) are guaranteed to return None. Most standard iterators are fused. This allows consumers to potentially optimize by not needing to call next() again after the first None. Custom iterators should uphold this behavior if possible and can implement this marker trait.

13.5 Performance: Zero-Cost Abstractions

A critical advantage of Rust’s iterators, especially relevant for C programmers concerned about abstraction overhead, is that they are typically zero-cost abstractions. This means that using high-level, composable iterator chains usually compiles down to machine code that is just as efficient as (and sometimes more efficient than, due to better optimization opportunities) a carefully handwritten C-style loop performing the same logic.

How Rust Achieves This:

Monomorphization: When generic functions or traits like Iterator are used with concrete types (e.g., iterating over a Vec<i32>), the Rust compiler generates specialized versions of the code for those specific types at compile time. The generic iter().map(...).filter(...).sum() becomes specialized code operating directly on i32 values and vector internals.
Inlining: The compiler aggressively inlines the small functions involved in iteration, particularly the next() method implementations and the closures provided to adapters like map and filter. This eliminates the overhead associated with function calls within the loop.
LLVM Optimizations: After monomorphization and inlining, the compiler’s backend (LLVM) sees a straightforward loop structure. It can then apply standard, powerful loop optimizations (like loop unrolling, vectorization where applicable using SIMD instructions, instruction reordering) just as effectively as it could for a manual C loop.

Lazy Evaluation Benefit: The lazy nature of iterator adapters (map, filter, etc.) also contributes to performance. Computation is only performed when items are requested by a consumer (or the next adapter). If an operation short-circuits (e.g., find, any, all), work on the remaining elements is entirely skipped, potentially saving significant computation compared to algorithms that might process an entire collection first before filtering or searching.

// Example comparing iterator chain vs manual loop
fn main() {
    let numbers: Vec<i32> = (1..=1000).collect(); // A reasonably sized vector

    // High-level, declarative iterator chain
    let sum_of_squares_of_evens_iterator: i64 = numbers
        .iter()              // Yields &i32
        .filter(|&&x| x % 2 == 0) // Yields &i32 for evens
        .map(|&x| (x as i64) * (x as i64)) // Yields i64 (squares)
        .sum();              // Consumes and sums the squares

    // Equivalent manual loop (lower-level, imperative)
    let mut sum_manual: i64 = 0;
    for &num_ref in &numbers { // Iterate by reference
        let num = num_ref; // Dereference
        if num % 2 == 0 {
            sum_manual += (num as i64) * (num as i64);
        }
    }

    // In optimized builds (`cargo run --release`), the generated machine code
    // for both versions is often identical or extremely close in performance.
    // The iterator version is arguably more readable.
    println!("Iterator sum: {}", sum_of_squares_of_evens_iterator);
    println!("Manual loop sum: {}", sum_manual);
    assert_eq!(sum_of_squares_of_evens_iterator, sum_manual);
}

Rust’s iterators allow developers to write clear, expressive, and composable code for data processing without the performance penalty often associated with high-level abstractions in other languages. This makes them a powerful and idiomatic tool even for systems programming.

13.6 Practical Examples

Let’s see how iterators are used for typical programming tasks.

13.6.1 Processing Lines from a File Safely

Iterators shine when dealing with I/O, allowing robust handling of potential errors and easy data transformation.

// Objective: Read a file containing numbers (one per line), potentially
// mixed with invalid lines or empty lines, and sum the valid numbers.
use std::fs::{self, File};
use std::io::{self, BufRead, BufReader};
use std::path::Path;

// Function to read file and sum valid numbers
fn sum_numbers_in_file(path: &Path) -> io::Result<i64> {
    let file = File::open(path)?; // Open file, ? propagates errors
    let reader = BufReader::new(file); // Use buffered reader for efficiency

    // Process lines using iterator chain
    let sum = reader.lines() // Produces an iterator yielding io::Result<String>
        .filter_map(|line_result| {
            // Stage 1: Handle potential I/O errors from reading lines
            line_result.ok() // Discard lines with I/O errors, keep Ok(String)
        })
        .filter_map(|line| {
            // Stage 2: Handle potential parsing errors
            line.trim().parse::<i64>().ok()
            // Trim whitespace, attempt parse, keep Ok(i64)
        })
        .sum(); // Sum the successfully parsed i64 values

    Ok(sum)
}

fn main() {
    let filename = "numbers_example.txt";
    let file_path = Path::new(filename);

    // Create a dummy file for the example using fs::write
    let content = "10\n20\n  \nthirty\n40\n-5\n invalid entry ";
    if let Err(e) = fs::write(file_path, content) {
        eprintln!("Failed to create dummy file: {}", e);
        return;
    }

    // Call the function and handle the result
    match sum_numbers_in_file(file_path) {
        Ok(total) => println!("Sum from file '{}': {}", filename, total),
        // Expected: 10 + 20 + 40 - 5 = 65
        Err(e) => eprintln!("Error processing file '{}': {}", filename, e),
    }

    // Clean up the dummy file (ignore potential error)
    let _ = fs::remove_file(file_path);
}

Here, filter_map elegantly handles two potential failure points in the pipeline: I/O errors during line reading (reader.lines() yields Result<String>) and parsing errors (parse() yields Result<i64>). The core logic remains concise and focused on the successful data transformations.

13.6.2 Functional-Style Data Transformation

Iterator chains allow complex data transformations to be expressed clearly and declaratively.

fn main() {
    let names = vec!["  alice ", " BOB", "   ", "charlie  ", "DAVID ", ""];

    let processed_names: Vec<String> = names
        .into_iter() // Consume the Vec<&str>, yields owned &str
        .map(|s| s.trim()) // Trim whitespace -> yields &str
        .filter(|s| !s.is_empty()) // Remove empty strings -> yields non-empty &str
        .map(|s| { // Convert to Title Case -> yields owned String
            let mut chars = s.chars();
            match chars.next() {
                None => String::new(), // Should not happen due to previous filter
                Some(first_char) => {
                    // Convert first char to uppercase, rest to lowercase
                    first_char.to_uppercase().collect::<String>()
                        + &chars.as_str().to_lowercase()
                }
            }
        })
        .collect(); // Collect the resulting Strings into a Vec<String>

    println!("Processed Names: {:?}", processed_names);
    // Output: Processed Names: ["Alice", "Bob", "Charlie", "David"]
}

This chain clearly expresses the steps: take ownership, trim whitespace, remove empty strings, convert to title case, and collect into a new vector. Each step is distinct and easy to understand.

13.7 Iterating Over Complex Structures: Binary Tree Example

Iterators are not limited to linear sequences like vectors or arrays. They can encapsulate the traversal logic for more complex data structures, such as trees or graphs, providing a standard Iterator interface for consuming code.

Here’s an example of implementing an in-order traversal iterator for a simple binary tree. We use Rc<RefCell<TreeNode<T>>> to handle shared ownership and potential mutation (though mutation isn’t used in this traversal itself), which is common in graph-like structures in Rust where nodes might be reachable via multiple paths.

use std::rc::Rc;
use std::cell::RefCell;
use std::collections::VecDeque; // Using VecDeque as a stack

// Node definition using shared ownership via Rc and interior mutability via RefCell
type TreeNodeLink<T> = Option<Rc<RefCell<TreeNode<T>>>>;

#[derive(Debug)]
struct TreeNode<T> {
    value: T,
    left: TreeNodeLink<T>,
    right: TreeNodeLink<T>,
}

impl<T> TreeNode<T> {
    // Helper to create a new node wrapped in Rc<RefCell<...>>
    fn new(value: T) -> Rc<RefCell<Self>> {
        Rc::new(RefCell::new(TreeNode {
            value,
            left: None,
            right: None,
        }))
    }
}

// Iterator struct for in-order traversal
struct InOrderIter<T: Clone> { // Require T: Clone to yield owned values
    // Stack holds nodes waiting to be visited (after their left subtree is done)
    stack: VecDeque<Rc<RefCell<TreeNode<T>>>>,
    // Current node pointer, used to navigate down left branches
    current: TreeNodeLink<T>,
}

impl<T: Clone> InOrderIter<T> {
    // Creates a new iterator starting traversal from the root
    fn new(root: TreeNodeLink<T>) -> Self {
        let mut iter = InOrderIter {
            stack: VecDeque::new(),
            current: root,
        };
        // Initialize by pushing the left spine onto the stack
        iter.push_left_spine();
        iter
    }

    // Helper: Pushes the current node and all its left children onto the stack.
    // Sets `self.current` to None after finishing.
    fn push_left_spine(&mut self) {
        while let Some(node) = self.current.take() { // Take ownership of current link
            self.stack.push_back(node.clone()); // Push node onto stack
            // Prepare to move left: borrow immutably to get left child link
            let left_link = node.borrow().left.clone();
            self.current = left_link; // Update current to the left child
        }
    }
}

impl<T: Clone> Iterator for InOrderIter<T> {
    type Item = T; // Yield owned copies of node values

    fn next(&mut self) -> Option<Self::Item> {
        // If current is Some, it means we just moved right from a popped node.
        // Push the new current node and its left spine onto the stack.
        if self.current.is_some() {
             self.push_left_spine();
        }

        // Pop the next node from the stack (this is the next in-order node)
        if let Some(node_to_visit) = self.stack.pop_back() {
            // Borrow node to access value and right child
            let node_ref = node_to_visit.borrow();
            let value_to_return = node_ref.value.clone(); // Clone value for return

            // Prepare for the *next* call: move to the right child.
            // The next call to `next()` will handle pushing this right child
            // and its left spine (if it exists) via `push_left_spine`.
            self.current = node_ref.right.clone();

            Some(value_to_return)
        } else {
            // Stack is empty and current is None -> Traversal complete
            None
        }
    }
}

// Add a convenience method to initiate the iteration from a root node
impl<T: Clone> TreeNode<T> {
     // Creates the in-order iterator for a tree rooted at `link`
     fn in_order_iter(link: TreeNodeLink<T>) -> InOrderIter<T> {
         InOrderIter::new(link)
     }
}

fn main() {
    // Build a simple binary search tree:
    //         4
    //        / \
    //       2   6
    //      / \ / \
    //     1  3 5  7
    let root = TreeNode::new(4);
    let node1 = TreeNode::new(1);
    let node3 = TreeNode::new(3);
    let node5 = TreeNode::new(5);
    let node7 = TreeNode::new(7);

    let node2 = TreeNode::new(2);
    node2.borrow_mut().left = Some(node1.clone());
    node2.borrow_mut().right = Some(node3.clone());

    let node6 = TreeNode::new(6);
    node6.borrow_mut().left = Some(node5.clone());
    node6.borrow_mut().right = Some(node7.clone());

    root.borrow_mut().left = Some(node2.clone());
    root.borrow_mut().right = Some(node6.clone());

    // Use the iterator and collect the results
    println!("Tree nodes (in-order traversal):");
    let traversal: Vec<i32> = TreeNode::in_order_iter(Some(root)).collect();
    println!("{:?}", traversal); // Expected: [1, 2, 3, 4, 5, 6, 7]
    assert_eq!(traversal, vec![1, 2, 3, 4, 5, 6, 7]);

    // Example of using the iterator step-by-step with a single node tree
    let root_single = TreeNode::new(10);
    let mut iter_manual = TreeNode::in_order_iter(Some(root_single));
    assert_eq!(iter_manual.next(), Some(10));
    assert_eq!(iter_manual.next(), None);
    assert_eq!(iter_manual.next(), None); // Fused behavior
}

This example demonstrates how the Iterator trait can encapsulate complex stateful traversal logic (managing a stack and current node pointer for tree traversal), exposing it through the simple, standard next() interface familiar to users of standard collection iterators. The T: Clone bound is necessary here because the iterator only has shared references (Rc<RefCell<...>>) to the nodes but needs to yield owned T values. An alternative design could yield references or require T: Copy.

13.8 Summary

Rust’s iterators are a fundamental and highly effective feature, promoting safe, efficient, and expressive code for processing sequences and traversable structures.

Core Traits: Iterator defines the sequence production via next(). IntoIterator enables types to be used in for loops and provide iterators via into_iter().
Iteration Modes: Collections typically offer iter() (yielding &T), iter_mut() (yielding &mut T), and into_iter() (yielding T), allowing flexible access based on borrowing and ownership needs. for loops implicitly use the appropriate mode.
Adapters & Consumers: Adapters (map, filter, zip, etc.) are lazy, chainable transformations returning new iterators. Consumers (collect, sum, for_each, find, etc.) are eager methods that drive the iteration to produce a result or side effect, consuming the iterator in the process.
Custom Iterators: Implementing the required next() method for the Iterator trait allows any type to define a sequence and automatically grants access to the rich set of default adapter and consumer methods. For custom collections, implementing IntoIterator for the type and its references provides idiomatic for loop integration. Leveraging standard library iterators (e.g., for internal arrays/slices) via delegation can significantly reduce boilerplate.
Zero-Cost Abstraction: Rust’s compiler optimizations (monomorphization, inlining, LLVM backend) ensure that iterator chains generally perform on par with equivalent handwritten C-style loops, providing high-level abstraction without sacrificing speed.
Versatility: Iterators are powerful tools for more than just linear collections; they effectively handle I/O streams, generators, and complex data structure traversals (like trees and graphs).

For programmers migrating from C, embracing Rust’s iterators is crucial for writing idiomatic and effective Rust code. They offer a robust, declarative approach to handling data sequences, shifting focus from manual index/pointer management to the high-level logic of data transformation, all while benefiting from Rust’s strong safety guarantees and impressive performance.

Keyboard shortcuts

Rust for C-Programmers