vec_mut_scan：高效遍历与修改可变向量元素的Rust工具

简介

vec_mut_scan是一个专为Rust设计的可变向量扫描库，它提供了高效的方法来遍历和修改可变向量（Vec<T>）中的元素。该库特别适用于需要在遍历过程中同时修改向量元素的场景，避免了传统迭代器可能带来的借用检查器冲突。

主要特性

• 安全的可变遍历：允许在遍历过程中修改向量元素
• 高性能：采用底层指针操作，避免不必要的开销
• 简洁API：提供直观易用的接口
• 零依赖：纯Rust实现，无外部依赖

安装方法

在Cargo.toml中添加依赖：

[dependencies]
vec_mut_scan = "0.1.0"

基本用法

简单示例

use vec_mut_scan::VecMutScan;

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    
    // 创建可变扫描器
    let mut scanner = VecMutScan::new(&mut vec);
    
    // 遍历并修改元素
    while let Some(element) = scanner.next() {
        *element *= 2; // 将每个元素乘以2
    }
    
    assert_eq!(vec, [2, 4, 6, 8, 10]);
}

带索引的遍历

use vec_mut_scan::VecMutScan;

fn main() {
    let mut vec = vec!["a", "b", "c", "d"];
    let mut scanner = VecMutScan::new(&mut vec);
    
    while let Some((index, element)) = scanner.next_with_index() {
        *element = match index {
            0 => "first",
            1 => "second",
            2 => "third",
            _ => "other"
        };
    }
    
    assert_eq!(vec, ["first", "second", "third", "other"]);
}

条件修改示例

use vec_mut_scan::VecMutScan;

fn main() {
    let mut numbers = vec![1, -2, 3, -4, 5];
    let mut scanner = VecMutScan::new(&mut numbers);
    
    while let Some(num) = scanner.next() {
        if *num < 0 {
            *num = 0; // 将所有负数替换为0
        }
    }
    
    assert_eq!(numbers, [1, 0, 3, 0, 5]);
}

高级用法

跳过元素

use vec_mut_scan::VecMutScan;

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    let mut scanner = VecMutScan::new(&mut vec);
    
    // 跳过前两个元素
    scanner.skip(2);
    
    while let Some(element) = scanner.next() {
        *element += 10;
    }
    
    assert_eq!(vec, [1, 2, 13, 14, 15]);
}

重置扫描器

use vec_mut_scan::VecMutScan;

fn main() {
    let mut vec = vec![1, 2, 3];
    let mut scanner = VecMutScan::new(&mut vec);
    
    // 第一次遍历
    while let Some(element) = scanner.next() {
        *element += 1;
    }
    
    // 重置扫描器重新开始
    scanner.reset();
    
    // 第二次遍历
    while let Some(element) = scanner.next() {
        *element *= 2;
    }
    
    assert_eq!(vec, [4, 6, 8]); // (1+1)*2=4, (2+1)*2=6, (3+1)*2=8
}

完整示例demo

use vec_mut_scan::VecMutScan;

fn main() {
    // 示例1: 基本数值操作
    println!("=== 基本数值操作示例 ===");
    let mut numbers = vec![10, 20, 30, 40, 50];
    let mut scanner = VecMutScan::new(&mut numbers);
    
    while let Some(num) = scanner.next() {
        *num += 5; // 每个元素加5
    }
    println!("加5后的结果: {:?}", numbers);
    
    // 示例2: 字符串处理
    println!("\n=== 字符串处理示例 ===");
    let mut words = vec!["hello", "world", "rust", "programming"];
    let mut word_scanner = VecMutScan::new(&mut words);
    
    while let Some((index, word)) = word_scanner.next_with_index() {
        *word = match index {
            0 => "HELLO",
            1 => "WORLD",
            2 => "RUST",
            _ => "PROGRAMMING"
        };
    }
    println!("处理后的字符串: {:?}", words);
    
    // 示例3: 条件过滤和修改
    println!("\n=== 条件过滤示例 ===");
    let mut scores = vec![85, 92, 78, 60, 95, 88];
    let mut score_scanner = VecMutScan::new(&mut scores);
    
    while let Some(score) = score_scanner.next() {
        if *score < 80 {
            *score = 80; // 将低于80分的分数提升到80分
        }
    }
    println!("调整后的分数: {:?}", scores);
    
    // 示例4: 高级用法组合
    println!("\n=== 高级用法组合示例 ===");
    let mut data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    let mut data_scanner = VecMutScan::new(&mut data);
    
    // 跳过前3个元素
    data_scanner.skip(3);
    
    // 修改剩余元素
    while let Some(element) = data_scanner.next() {
        *element *= 10;
    }
    println!("跳过前3个元素后的结果: {:?}", data);
    
    // 重置扫描器并重新处理
    data_scanner.reset();
    while let Some(element) = data_scanner.next() {
        *element += 1;
    }
    println!("重置后再次处理的结果: {:?}", data);
}

#[test]
fn test_vec_mut_scan() {
    // 测试基本功能
    let mut test_vec = vec![1, 2, 3];
    let mut test_scanner = VecMutScan::new(&mut test_vec);
    
    while let Some(element) = test_scanner.next() {
        *element *= 2;
    }
    
    assert_eq!(test_vec, [2, 4, 6]);
    println!("测试通过!");
}

注意事项

1. 在遍历过程中不要对原始向量进行push/pop操作，这会导致未定义行为
2. 扫描器在遍历期间会持有向量的可变引用
3. 适用于需要高性能修改大量元素的场景

性能建议

• 对于大型向量，vec_mut_scan比传统的iter_mut().enumerate()更高效
• 避免在循环中创建新的扫描器实例
• 考虑批量处理来减少函数调用开销

这个库为需要高效遍历和修改可变向量的Rust开发者提供了一个安全且高性能的解决方案。