rust-iterator-collections

Rust 迭代器与集合

使用此技能，将集合代码改写为清晰、符合习惯的 Rust。优先使用能直接表达操作的迭代器和集合 API，同时清楚呈现所有权、内存分配和错误行为。

核心工作流

1. 确定输入的所有权模式：借用迭代、可变迭代或消耗式迭代。
2. 选择最简单的迭代器形式：iter、iter_mut、into_iter、范围、drain 或特定集合的方法。
3. 仅当结果代码更清晰时，才用适配器替代手动循环。对于复杂分支、提前修改或调试，保留显式循环。
4. 如果错误应导致提前终止，请使用可失败的迭代器消费方法，例如 collect::<Result<Vec<_>, _>>()、try_fold 和 try_for_each。
5. 对插入或更新逻辑使用 HashMap::entry 或 BTreeMap::entry。
6. 避免不必要的中间 Vec。尽可能链接迭代器，或扩展已有集合。
7. 测试空输入、单项输入、重复键、顺序预期以及错误是否会导致提前终止。

迭代器规则

• 如果函数只需要迭代，接受 impl IntoIterator<Item = T>。
• 当切片语义已足够时，使用 &[T]；避免使用 &Vec<T>。
• 使用 filter_map 实现映射后丢弃 None；当每个元素会展开为零个或多个元素时，使用 flat_map。
• 当它们能明确表达停止行为时，使用 map_while 或 scan 进行有状态转换。
• 在 collect 边界添加类型注解，不要在整个处理流水线中到处添加。
• 有意克隆迭代器元素时，优先使用 cloned 或 copied，而不是 map(|x| x.clone())。

集合规则

重构循环或审查集合修改时，请阅读 references/iterator-collection-patterns.md。

• 连续有序数据使用 Vec，在两端进行队列式推入或弹出时使用 VecDeque，优先队列使用 BinaryHeap，无序查找使用 HashMap，有序查找或范围查询使用 BTreeMap。
• 使用 retain、drain、splice 和 split_off，避免在单独遍历借用元素的同时修改集合。
• 默认构造开销较大时，使用 Entry::or_insert_with。
• 有意保留顺序。当迭代顺序属于行为的一部分时，不要将 BTreeMap 换成 HashMap。
• 仅在大小已知或性能分析表明重新分配会造成影响时，才预留容量。

审查清单

• 处理流水线清晰表达了所有权和错误行为。
• 不要在使用 entry 更简单时，先调用 contains_key 再调用 insert。
• 没有仅为了再次迭代而进行的、可避免的 collect::<Vec<_>>()。
• 仅当索引本身是领域概念时才使用索引。
• 在需要时，测试覆盖重复项、空输入和确定性顺序。