Rust双端迭代器增强库double-ended-peekable使用指南

概述

double-ended-peekable是一个Rust库，它为双端迭代器提供了增强的peek功能，允许你同时向前和向后查看迭代器中的元素而不会消耗它们。

功能特点

• 支持双向peek操作
• 保持原始迭代器的所有功能
• 零成本抽象（在Rust中意味着没有运行时开销）
• 与标准库的Peekable类似但功能更强大

安装

在Cargo.toml中添加依赖：

[dependencies]
double-ended-peekable = "0.1"

基本使用方法

创建双端peekable迭代器

use double_ended_peekable::DoubleEndedPeekableExt;

fn main() {
    let vec = vec![1, 2, 3, 4, 5];
    let mut iter = vec.into_iter().double_ended_peekable();
    
    // 现在可以使用双向peek功能
}

双向peek操作

let mut iter = vec![1, 2, 3, 4, 5].into_iter().double_ended_peekable();

// 向前peek
assert_eq!(iter.peek(), Some(&1));
assert_eq!(iter.peek_next(), Some(&2));

// 向后peek
assert_eq!(iter.peek_prev(), None);  // 还没有消耗任何元素

// 前进一个元素
iter.next();

// 现在可以向后peek了
assert_eq!(iter.peek_prev(), Some(&1));
assert_eq!(iter.peek(), Some(&2));
assert_eq!(iter.peek_next(), Some(&3));

完整示例

use double_ended_peekable::DoubleEndedPeekableExt;

fn process_sequence<I: DoubleEndedIterator>(iter: I) {
    let mut iter = iter.double_ended_peekable();
    
    while let Some(current) = iter.next() {
        let prev = iter.peek_prev().copied();
        let next = iter.peek().copied();
        
        println!(
            "Processing {}: previous was {:?}, next is {:?}",
            current, prev, next
        );
        
        // 根据前后元素决定处理逻辑
        match (prev, next) {
            (Some(p), Some(n)) if p < current && n > current => {
                println!("  -> Peak detected!");
            },
            (Some(p), Some(n)) if p > current && n < current => {
                println!("  -> Valley detected!");
            },
            _ => {}
        }
    }
}

fn main() {
    let data = vec![1, 3, 5, 4, 2, 6, 8];
    process_sequence(data.into_iter());
}

高级用法

与双端迭代器结合使用

use double_ended_peekable::DoubleEndedPeekableExt;

fn main() {
    let mut iter = (1..=10).double_ended_peekable();
    
    // 从前面消耗几个元素
    assert_eq!(iter.next(), Some(1));
    assert_eq!(iter.next(), Some(2));
    
    // 从后面消耗几个元素
    assert_eq!(iter.next_back(), Some(10));
    assert_eq!(iter.next_back(), Some(9));
    
    // 现在peek各个方向
    assert_eq!(iter.peek(), Some(&3));      // 下一个前面的元素
    assert_eq!(iter.peek_next(), Some(&4));  // 下下个前面的元素
    assert_eq!(iter.peek_prev(), Some(&2));  // 前一个前面的元素
    assert_eq!(iter.peek_back(), Some(&8));  // 下一个后面的元素
}

实现自定义逻辑

use double_ended_peekable::DoubleEndedPeekableExt;

fn find_symmetric_pairs<I: DoubleEndedIterator<Item = i32>>(iter: I) -> Vec<(i32, i32)> {
    let mut iter = iter.double_ended_peekable();
    let mut result = Vec::new();
    
    while let (Some(front), Some(back)) = (iter.peek(), iter.peek_back()) {
        if front == back {
            result.push((*front, *back));
            iter.next();
            iter.next_back();
        } else if front < back {
            iter.next();
        } else {
            iter.next_back();
        }
    }
    
    result
}

fn main() {
    let nums = vec![1, 2, 3, 4, 5, 4, 3, 2, 1];
    let pairs = find_symmetric_pairs(nums.into_iter());
    println!("Symmetric pairs: {:?}", pairs);
    // 输出: Symmetric pairs: [(1, 1), (2, 2), (3, 3), (4, 4)]
}

完整示例demo

下面是一个结合了多种功能的完整示例，展示如何在实际场景中使用double-ended-peekable：

use double_ended_peekable::DoubleEndedPeekableExt;

// 处理数字序列，检测极值和趋势
fn analyze_sequence<I: DoubleEndedIterator<Item = i32>>(iter: I) {
    let mut iter = iter.double_ended_peekable();
    let mut count = 0;
    
    println!("开始分析序列...");
    
    while let Some(current) = iter.next() {
        count += 1;
        let prev = iter.peek_prev().copied();
        let next = iter.peek().copied();
        
        // 打印当前位置信息
        println!("\n元素 #{}: {}", count, current);
        println!("前驱元素: {:?}, 后继元素: {:?}", prev, next);
        
        // 检测极值点
        match (prev, next) {
            (Some(p), Some(n)) if p < current && n < current => {
                println!("↗↘ 检测到局部最大值: {}", current);
            },
            (Some(p), Some(n)) if p > current && n > current => {
                println!("↘↗ 检测到局部最小值: {}", current);
            },
            _ => {}
        }
        
        // 检测趋势
        match (prev, next) {
            (Some(p), Some(n)) if p < current && current < n => {
                println!("↑ 上升趋势");
            },
            (Some(p), Some(n)) if p > current && current > n => {
                println!("↓ 下降趋势");
            },
            _ => {}
        }
        
        // 如果到达序列末尾
        if iter.peek().is_none() {
            println!("已到达序列末尾");
        }
    }
    
    println!("分析完成，共处理{}个元素", count);
}

fn main() {
    // 创建一个测试序列
    let test_data = vec![1, 2, 3, 2, 1, 0, 1, 2, 3, 4, 3, 2];
    
    println!("测试序列: {:?}", test_data);
    analyze_sequence(test_data.into_iter());
}

注意事项

1. 该库需要迭代器实现DoubleEndedIterator trait
2. peek_prev()只有在已经消耗至少一个元素后才会返回Some
3. 所有peek操作都不会消耗迭代器中的元素
4. 性能与标准库的Peekable相当

这个库特别适合需要同时查看前后元素的算法场景，如解析器、模式匹配等需要"前瞻"和"后顾"的情况。