自定义迭代器 ​

核心概念 ​

自定义迭代器只需要两步:定义一个结构体来保存迭代状态,然后为它实现 Iterator trait(定义 type Item 和 next() 方法)。实现后就自动获得标准库提供的几十个默认方法(map、filter、fold、collect 等),也可以直接用在 for 循环中。自定义迭代器可以表示任何序列——数学序列、数据流、状态机等。

rust
// 步骤1:定义状态结构体
struct Counter {
    current: u32,
    max: u32,
}

impl Counter {
    fn new(max: u32) -> Self {
        Counter { current: 0, max }
    }
}

// 步骤2:实现 Iterator trait
impl Iterator for Counter {
    type Item = u32;  // 产出的元素类型

    fn next(&mut self) -> Option<u32> {
        if self.current < self.max {
            self.current += 1;
            Some(self.current)
        } else {
            None
        }
    }
}

fn main() {
    // 用 for 循环
    for n in Counter::new(5) {
        print!("{} ", n);
    }
    println!();  // 1 2 3 4 5

    // 用迭代器方法
    let sum: u32 = Counter::new(10).sum();
    println!("1到10的和: {}", sum);

    let evens: Vec<u32> = Counter::new(20)
        .filter(|&n| n % 2 == 0)
        .collect();
    println!("偶数: {:?}", evens);
}

无穷迭代器 ​

rust
// 无穷迭代器:next() 永远返回 Some
struct NaturalNumbers {
    current: u64,
}

impl NaturalNumbers {
    fn new() -> Self {
        NaturalNumbers { current: 0 }
    }

    fn starting_from(n: u64) -> Self {
        NaturalNumbers { current: n.saturating_sub(1) }
    }
}

impl Iterator for NaturalNumbers {
    type Item = u64;

    fn next(&mut self) -> Option<u64> {
        self.current += 1;
        Some(self.current)  // 永远返回 Some
    }
}

// 素数迭代器(无穷)
struct Primes {
    found: Vec<u64>,
    candidate: u64,
}

impl Primes {
    fn new() -> Self {
        Primes {
            found: Vec::new(),
            candidate: 2,
        }
    }

    fn is_prime(&self, n: u64) -> bool {
        let limit = (n as f64).sqrt() as u64;
        for &p in &self.found {
            if p > limit { break; }
            if n % p == 0 { return false; }
        }
        true
    }
}

impl Iterator for Primes {
    type Item = u64;

    fn next(&mut self) -> Option<u64> {
        while !self.is_prime(self.candidate) {
            self.candidate += 1;
        }
        let prime = self.candidate;
        self.found.push(prime);
        self.candidate += 1;
        Some(prime)
    }
}

fn main() {
    // 自然数
    let first_ten: Vec<u64> = NaturalNumbers::new().take(10).collect();
    println!("前10个自然数: {:?}", first_ten);

    let from_100: Vec<u64> = NaturalNumbers::starting_from(100).take(5).collect();
    println!("从100开始: {:?}", from_100);

    // 素数
    let first_primes: Vec<u64> = Primes::new().take(15).collect();
    println!("前15个素数: {:?}", first_primes);

    let sum_of_primes: u64 = Primes::new()
        .take_while(|&p| p < 100)
        .sum();
    println!("100以内素数之和: {}", sum_of_primes);
}

带生命周期的迭代器 ​

rust
// 迭代切片中的非空行
struct NonEmptyLines<'a> {
    lines: &'a [&'a str],
    pos: usize,
}

impl<'a> NonEmptyLines<'a> {
    fn new(lines: &'a [&'a str]) -> Self {
        NonEmptyLines { lines, pos: 0 }
    }
}

impl<'a> Iterator for NonEmptyLines<'a> {
    type Item = &'a str;

    fn next(&mut self) -> Option<&'a str> {
        while self.pos < self.lines.len() {
            let line = self.lines[self.pos];
            self.pos += 1;
            if !line.trim().is_empty() {
                return Some(line);
            }
        }
        None
    }
}

fn main() {
    let text = vec![
        "第一行",
        "",
        "  ",
        "第四行",
        "",
        "第六行",
    ];

    let non_empty: Vec<&str> = NonEmptyLines::new(&text).collect();
    println!("非空行: {:?}", non_empty);

    let count = NonEmptyLines::new(&text).count();
    println!("非空行数: {}", count);
}

实现 DoubleEndedIterator ​

rust
// 支持从两端迭代
struct Range {
    front: i32,
    back: i32,
}

impl Range {
    fn new(start: i32, end: i32) -> Self {
        Range { front: start, back: end }
    }
}

impl Iterator for Range {
    type Item = i32;

    fn next(&mut self) -> Option<i32> {
        if self.front < self.back {
            let val = self.front;
            self.front += 1;
            Some(val)
        } else {
            None
        }
    }
}

impl DoubleEndedIterator for Range {
    fn next_back(&mut self) -> Option<i32> {
        if self.front < self.back {
            self.back -= 1;
            Some(self.back)
        } else {
            None
        }
    }
}

fn main() {
    // 正向
    let forward: Vec<i32> = Range::new(1, 6).collect();
    println!("正向: {:?}", forward);

    // 反向(rev 需要 DoubleEndedIterator)
    let backward: Vec<i32> = Range::new(1, 6).rev().collect();
    println!("反向: {:?}", backward);

    // 两端交替取
    let mut iter = Range::new(1, 8);
    println!("前: {:?}", iter.next());       // Some(1)
    println!("后: {:?}", iter.next_back());  // Some(7)
    println!("前: {:?}", iter.next());       // Some(2)
    println!("后: {:?}", iter.next_back());  // Some(6)
}

基本示例 ​

实现一个完整的矩阵迭代器系统:

rust
#[derive(Debug, Clone)]
struct Matrix {
    data: Vec<Vec<i32>>,
    rows: usize,
    cols: usize,
}

impl Matrix {
    fn new(data: Vec<Vec<i32>>) -> Self {
        let rows = data.len();
        let cols = if rows > 0 { data[0].len() } else { 0 };
        Matrix { data, rows, cols }
    }

    // 按行迭代
    fn row_iter(&self) -> RowIter {
        RowIter { matrix: self, row: 0 }
    }

    // 按列迭代
    fn col_iter(&self) -> ColIter {
        ColIter { matrix: self, col: 0 }
    }

    // 对角线迭代
    fn diag_iter(&self) -> DiagIter {
        DiagIter { matrix: self, pos: 0 }
    }
}

// 行迭代器
struct RowIter<'a> {
    matrix: &'a Matrix,
    row: usize,
}

impl<'a> Iterator for RowIter<'a> {
    type Item = &'a Vec<i32>;

    fn next(&mut self) -> Option<&'a Vec<i32>> {
        if self.row < self.matrix.rows {
            let row = &self.matrix.data[self.row];
            self.row += 1;
            Some(row)
        } else {
            None
        }
    }
}

// 列迭代器(产出每列的元素组成的 Vec)
struct ColIter<'a> {
    matrix: &'a Matrix,
    col: usize,
}

impl<'a> Iterator for ColIter<'a> {
    type Item = Vec<i32>;

    fn next(&mut self) -> Option<Vec<i32>> {
        if self.col < self.matrix.cols {
            let column: Vec<i32> = self.matrix.data.iter()
                .map(|row| row[self.col])
                .collect();
            self.col += 1;
            Some(column)
        } else {
            None
        }
    }
}

// 对角线迭代器
struct DiagIter<'a> {
    matrix: &'a Matrix,
    pos: usize,
}

impl<'a> Iterator for DiagIter<'a> {
    type Item = i32;

    fn next(&mut self) -> Option<i32> {
        let size = self.matrix.rows.min(self.matrix.cols);
        if self.pos < size {
            let val = self.matrix.data[self.pos][self.pos];
            self.pos += 1;
            Some(val)
        } else {
            None
        }
    }
}

fn main() {
    let matrix = Matrix::new(vec![
        vec![1, 2, 3],
        vec![4, 5, 6],
        vec![7, 8, 9],
    ]);

    // 按行迭代
    println!("=== 按行 ===");
    for row in matrix.row_iter() {
        let sum: i32 = row.iter().sum();
        println!("  {:?} → 行和={}", row, sum);
    }

    // 按列迭代
    println!("\n=== 按列 ===");
    for (i, col) in matrix.col_iter().enumerate() {
        let sum: i32 = col.iter().sum();
        println!("  第{}列: {:?} → 列和={}", i, col, sum);
    }

    // 对角线
    let diag: Vec<i32> = matrix.diag_iter().collect();
    println!("\n对角线: {:?}", diag);
    println!("对角线之和: {}", matrix.diag_iter().sum::<i32>());

    // 用迭代器方法组合
    let max_row_sum = matrix.row_iter()
        .map(|row| row.iter().sum::<i32>())
        .max()
        .unwrap();
    println!("最大行和: {}", max_row_sum);

    // 所有元素的平方和
    let sq_sum: i32 = matrix.row_iter()
        .flat_map(|row| row.iter())
        .map(|&x| x * x)
        .sum();
    println!("平方和: {}", sq_sum);
}

常见问题 ​

问题一:自定义迭代器需要实现哪些方法?

只需要实现 Iterator trait 的 next() 方法和定义 type Item。其他几十个方法(map、filter、fold 等)都有默认实现。可以选择性地覆盖 size_hint() 来提升性能。

问题二:自定义迭代器可以用 for 循环吗?

可以。实现了 Iterator 的类型自动实现 IntoIterator,所以可以直接用在 for 循环中。

问题三:什么是 size_hint?

size_hint() 返回 (usize, Option<usize>),表示迭代器剩余元素数量的下界和上界。collect 等方法用它来预分配内存。默认返回 (0, None),如果知道确切大小可以覆盖提升性能。

问题四:怎么让自定义迭代器支持 rev()?

需要额外实现 DoubleEndedIterator trait,提供 next_back() 方法。rev() 方法需要 DoubleEndedIterator bound。

适用场景 ​

  • 数学序列:斐波那契、素数、几何级数
  • 数据遍历:自定义集合的多种遍历方式
  • 状态机:每次 next() 推进一步
  • 流式数据:文件行、网络数据包

注意事项 ​

  • 只需实现 next() 和 type Item
  • 无穷迭代器的 next() 永远返回 Some
  • 返回 None 后应持续返回 None(融合语义)
  • 带引用的迭代器需要生命周期参数
  • 可选实现 DoubleEndedIterator 支持反向迭代
  • 可选覆盖 size_hint() 提升 collect 等方法的性能

总结 ​

自定义迭代器需要定义状态结构体并实现 Iterator trait(type Item 和 next() 方法)。实现后自动获得几十个默认方法并能用在 for 循环中。无穷迭代器的 next() 永远返回 Some,使用时必须用 take 限制。带引用的迭代器需要生命周期参数。实现 DoubleEndedIterator(next_back() 方法)可以支持 rev() 反向迭代。覆盖 size_hint() 可以帮助 collect 等方法预分配内存。自定义迭代器广泛用于数学序列、自定义集合遍历、状态机、流式数据处理等场景。