IntoIterator Trait ​

核心概念 ​

IntoIterator 是标准库中的 trait,定义了如何将一个类型转换为迭代器。for 循环实际上就是对 IntoIterator 的语法糖——for item in collection 会自动调用 collection.into_iter() 获取迭代器,然后反复调用 next()。IntoIterator 和 Iterator 的关系是:Iterator 定义了"如何逐个产出元素",IntoIterator 定义了"如何从一个集合/类型得到迭代器"。所有实现了 Iterator 的类型自动实现 IntoIterator(返回自身)。

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

    // for 循环底层调用 into_iter()
    for n in nums {
        // 这里 nums.into_iter() 被隐式调用
        // 消耗了 nums 的所有权
        print!("{} ", n);
    }
    println!();
    // nums 已经被消耗,不能再使用
    // println!("{:?}", nums);  // 编译错误

    // 显式调用 into_iter()
    let data = vec![10, 20, 30];
    let mut iter = data.into_iter();  // 消耗 data
    println!("{:?}", iter.next());  // Some(10)
    println!("{:?}", iter.next());  // Some(20)
}

IntoIterator trait 的定义 ​

rust
// 标准库中的简化定义:
// pub trait IntoIterator {
//     type Item;                      // 迭代器产出的元素类型
//     type IntoIter: Iterator<Item = Self::Item>;  // 迭代器的具体类型
//     fn into_iter(self) -> Self::IntoIter;        // 转换方法
// }

// Vec<T> 对 IntoIterator 有三种实现:
// 1. Vec<T>      -> into_iter()  -> 产出 T(消耗集合)
// 2. &Vec<T>     -> into_iter()  -> 产出 &T(借用集合)
// 3. &mut Vec<T> -> into_iter()  -> 产出 &mut T(可变借用集合)

fn main() {
    let mut data = vec![String::from("a"), String::from("b"), String::from("c")];

    // &data 的 into_iter() -> 产出 &String
    for item in &data {
        print!("{} ", item);  // item 是 &String
    }
    println!();

    // &mut data 的 into_iter() -> 产出 &mut String
    for item in &mut data {
        item.push_str("!");  // item 是 &mut String,可以修改
    }
    println!("{:?}", data);  // ["a!", "b!", "c!"]

    // data 的 into_iter() -> 产出 String(消耗)
    for item in data {
        print!("{} ", item);  // item 是 String
    }
    println!();
    // data 已被消耗
}

for 循环中的三种迭代方式 ​

写法调用产出类型集合是否消耗
for x in collectioncollection.into_iter()T是
for x in &collection(&collection).into_iter()&T否
for x in &mut collection(&mut collection).into_iter()&mut T否
rust
fn main() {
    let names = vec!["Alice", "Bob", "Charlie"];

    // 借用迭代:集合不被消耗
    for name in &names {
        println!("你好, {}!", name);
    }
    println!("集合仍在: {:?}", names);

    // 消耗迭代:集合被消耗
    let collected: Vec<String> = names.into_iter()
        .map(|n| n.to_uppercase())
        .collect();
    println!("转换后: {:?}", collected);
    // names 已不可用
}

为自定义类型实现 IntoIterator ​

rust
// 自定义集合
struct NumberBag {
    items: Vec<i32>,
}

impl NumberBag {
    fn new(items: Vec<i32>) -> Self {
        NumberBag { items }
    }
}

// 为 NumberBag 实现 IntoIterator(消耗版本)
impl IntoIterator for NumberBag {
    type Item = i32;
    type IntoIter = std::vec::IntoIter<i32>;

    fn into_iter(self) -> Self::IntoIter {
        self.items.into_iter()
    }
}

// 为 &NumberBag 实现 IntoIterator(借用版本)
impl<'a> IntoIterator for &'a NumberBag {
    type Item = &'a i32;
    type IntoIter = std::slice::Iter<'a, i32>;

    fn into_iter(self) -> Self::IntoIter {
        self.items.iter()
    }
}

// 为 &mut NumberBag 实现 IntoIterator(可变借用版本)
impl<'a> IntoIterator for &'a mut NumberBag {
    type Item = &'a mut i32;
    type IntoIter = std::slice::IterMut<'a, i32>;

    fn into_iter(self) -> Self::IntoIter {
        self.items.iter_mut()
    }
}

fn main() {
    let mut bag = NumberBag::new(vec![10, 20, 30, 40, 50]);

    // 借用迭代
    println!("借用:");
    for num in &bag {
        print!("{} ", num);
    }
    println!();

    // 可变借用迭代
    for num in &mut bag {
        *num *= 2;
    }
    println!("翻倍后:");
    for num in &bag {
        print!("{} ", num);
    }
    println!();

    // 消耗迭代
    let sum: i32 = bag.into_iter().sum();
    println!("总和: {}", sum);
}

IntoIterator 在泛型中的使用 ​

rust
use std::fmt::Display;

// 接受任何可迭代的类型
fn print_all<I>(iterable: I)
where
    I: IntoIterator,
    I::Item: Display,
{
    for item in iterable {
        print!("{} ", item);
    }
    println!();
}

// 统计满足条件的元素
fn count_matching<I, F>(iterable: I, predicate: F) -> usize
where
    I: IntoIterator,
    F: Fn(&I::Item) -> bool,
{
    let mut count = 0;
    for item in iterable {
        if predicate(&item) {
            count += 1;
        }
    }
    count
}

// 查找第一个满足条件的元素
fn find_first<I>(iterable: I, predicate: impl Fn(&I::Item) -> bool) -> Option<I::Item>
where
    I: IntoIterator,
{
    for item in iterable {
        if predicate(&item) {
            return Some(item);
        }
    }
    None
}

fn main() {
    // Vec
    print_all(vec![1, 2, 3]);

    // 数组
    print_all([10, 20, 30]);

    // Range
    print_all(1..=5);

    // 统计
    let nums = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    let even_count = count_matching(&nums, |&&n| n % 2 == 0);
    println!("偶数个数: {}", even_count);

    // 查找
    let found = find_first(vec![10, 25, 30, 45], |n| n > &20);
    println!("第一个>20: {:?}", found);
}

基本示例 ​

实现一个矩阵类型,提供行迭代和元素迭代:

rust
use std::fmt;

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

impl Matrix {
    fn new(rows: usize, cols: usize) -> Self {
        Matrix {
            data: vec![vec![0.0; cols]; rows],
            rows,
            cols,
        }
    }

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

    fn set(&mut self, row: usize, col: usize, value: f64) {
        self.data[row][col] = value;
    }
}

impl fmt::Display for Matrix {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for row in &self.data {
            let formatted: Vec<String> = row.iter().map(|v| format!("{:6.1}", v)).collect();
            writeln!(f, "[ {} ]", formatted.join(", "))?;
        }
        Ok(())
    }
}

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

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

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

// 为 &Matrix 实现 IntoIterator(按行迭代)
impl<'a> IntoIterator for &'a Matrix {
    type Item = &'a Vec<f64>;
    type IntoIter = RowIter<'a>;

    fn into_iter(self) -> RowIter<'a> {
        RowIter { matrix: self, row: 0 }
    }
}

// 元素迭代器(消耗版本)
struct ElementIter {
    data: Vec<f64>,
    pos: usize,
}

impl Iterator for ElementIter {
    type Item = f64;

    fn next(&mut self) -> Option<f64> {
        if self.pos < self.data.len() {
            let val = self.data[self.pos];
            self.pos += 1;
            Some(val)
        } else {
            None
        }
    }
}

impl IntoIterator for Matrix {
    type Item = f64;
    type IntoIter = ElementIter;

    fn into_iter(self) -> ElementIter {
        let flat: Vec<f64> = self.data.into_iter().flat_map(|row| row).collect();
        ElementIter { data: flat, pos: 0 }
    }
}

fn main() {
    let matrix = Matrix::from_data(vec![
        vec![1.0, 2.0, 3.0],
        vec![4.0, 5.0, 6.0],
        vec![7.0, 8.0, 9.0],
    ]);

    println!("矩阵:");
    print!("{}", matrix);

    // 按行迭代(借用)
    println!("按行迭代:");
    for row in &matrix {
        let sum: f64 = row.iter().sum();
        println!("  {:?} → 行和: {:.1}", row, sum);
    }

    // matrix 仍可用
    println!("行数: {}, 列数: {}", matrix.rows, matrix.cols);

    // 按元素迭代(消耗)
    let sum: f64 = matrix.into_iter().sum();
    println!("所有元素之和: {:.1}", sum);
}

常见问题 ​

问题一:into_iter() 和 iter() 有什么区别?

into_iter() 是 IntoIterator trait 的方法,根据调用者的类型决定产出 T、&T 或 &mut T。iter() 是集合类型自身定义的方法,总是产出 &T。iter_mut() 总是产出 &mut T。

问题二:为什么 for x in vec 会消耗 vec?

因为 Vec<T> 的 IntoIterator 实现调用 into_iter(self) 获取所有权,产出 T。如果不想消耗,用 for x in &vec。

问题三:所有 Iterator 都实现了 IntoIterator 吗?

是的。标准库有一个毯子实现:impl<I: Iterator> IntoIterator for I,所以所有迭代器都可以直接用在 for 循环中。

问题四:自定义类型需要同时实现三种 IntoIterator 吗?

不是必须的,但推荐至少实现消耗版本(for Self)和借用版本(for &Self)。如果集合的元素可以修改,再加上可变借用版本(for &mut Self)。

适用场景 ​

  • 自定义集合:让集合可以用 for 循环遍历
  • 泛型函数:接受任何可迭代类型
  • 适配器模式:包装已有集合提供不同的迭代视角
  • 类型转换:将非集合类型转换为可迭代的形式

注意事项 ​

  • for 循环隐式调用 into_iter()
  • for x in collection 消耗集合,for x in &collection 借用
  • 所有 Iterator 自动实现 IntoIterator
  • 自定义类型建议实现 Self、&Self 两种 IntoIterator
  • IntoIterator 的 IntoIter 关联类型必须实现 Iterator
  • 泛型函数中用 I: IntoIterator 比 I: Iterator 更通用

总结 ​

IntoIterator trait 定义了如何将一个类型转换为迭代器,是 for 循环的底层机制。for item in collection 会调用 collection.into_iter() 获取迭代器。标准库的集合类型(Vec、HashMap 等)对 Self、&Self、&mut Self 分别实现了 IntoIterator,产出 T、&T、&mut T。自定义类型通过实现 IntoIterator 就能用 for 循环遍历。在泛型函数中用 I: IntoIterator 可以接受任何可迭代类型。所有 Iterator 自动实现 IntoIterator。