C++标准库中的std::multimap允许同一个键关联多个值，这与std::map单值映射的设计截然不同。当我们需要提取某个键对应的所有值时，直接使用operator[]在multimap上是不可用的，因为键不是唯一的。这时候就需要借助成员函数equal_range，它可以一次性返回一个迭代器对，精准标定所有匹配元素的边界。本文将深入剖析equal_range的用法，并结合现代C++特性为你提供最优雅的遍历方案。
理解std::multimap的键值存储结构
std::multimap底层通常基于红黑树实现，元素依据键的顺序自动排序。与std::map不同的是，它允许存在多个键值相同的元素，这些元素在树中的存储位置是连续的，形成了一个“等效键区间”。当我们插入多个键为1的值时，它们会按照插入顺序在内部有序地排列在一起。这为equal_range的高效实现奠定了物理基础——它只需在有序序列中定位到第一个不小于给定键的元素，以及第一个大于给定键的元素，这两个位置之间的所有元素键都等于给定值。
假设我们有一个记录学生某门课程多次考试分数的multimap，键是学生学号，值是分数。同一个学生可能参加多次考试，因此会有多个同键条目。在这样的场景下，我们想要查看某位学生的所有成绩，就需要精准地获取该键对应的所有元素，而不可能有默认的operator[]来返回单一值。这时迭代器范围的概念就变得非常实用。
为了真正理解equal_range，我们需要先建立对multimap内部顺序性的认知。插入元素(1, 90)、(1, 85)、(2, 88)后，在内存中键为1的两个元素会紧邻存放，且由于multimap的稳定插入特性，先插入的会出现在前面（除非是借助带位置的插入调整顺序）。遍历整个容器时，同等键的元素会连续出现，这与unordered_multimap的散列存储形成鲜明对比，后者同等键的元素会被分配到同一个桶中，但顺序无保证。只有基于红黑树的有序容器才能提供高效的equal_range（对数复杂度）。
equal_range函数详解：返回值与使用模式
equal_range的声明通常为std::pair，它返回一个包含两个迭代器的pair，其中first指向第一个不小于key的元素（即lower_bound），second指向第一个大于key的元素（即upper_bound）。如果给定的键不存在，两个迭代器都会指向end()或者指向同一个适合插入该键的位置，此时范围为空。这意味着检查键是否存在也十分简单：只要first == second，就说明没有匹配的元素。
在现代C++中，我们可以利用结构化绑定让代码更加清晰：
std::multimap<int, std::string> mm = {
{1, "apple"}, {1, "avocado"}, {2, "banana"}, {1, "apricot"}
};
auto [lower, upper] = mm.equal_range(1);
for (auto it = lower; it != upper; ++it) {
std::cout << it->second << ' '; // 输出: apple avocado apricot
}
这段代码中，lower指向键为1的第一个元素，upper指向键为2的第一个元素。迭代器区间[lower, upper)正好包含了所有键等于1的元素。注意元素的遍历顺序是按照键的排序规则（即std::less）确定的，所以学号1的所有值会按插入顺序出现，但实际顺序依赖于multimap的比较函数，键相等时则保持插入顺序。这种稳定的插入顺序是标准库的保证。
当容器被声明为const时，equal_range会返回std::pair，以便在只读语境下安全使用。如果代码需要修改容器中的值（注意不能修改键，因为键是const的），可以使用std::multimap::iterator来接收返回值。
结合范围for循环与结构化绑定进行优雅遍历
C++20引入了范围库（Ranges），但对于equal_range返回的传统迭代器对，我们同样可以利用范围for循环来简化代码，临时构建一个std::ranges::subrange即可。然而即便在没有C++20的场合，借助一个小技巧依旧能写得很干净：将equal_range返回的两个迭代器视为一个可以迭代的区间，然后直接用for循环遍历。一种常见做法是使用for (auto it = lower; it != upper; ++it)，但别忘了可以通过auto引用直接绑定值：
auto [lower, upper] = mm.equal_range(1);
for (auto it = lower; it != upper; ++it) {
const auto& val = it->second; // 可以获取值引用，避免拷贝
std::cout << val << 'n';
}
如果频繁获取某个键的范围，并希望像操作普通容器那样使用范围for，可以封装一个辅助函数：
template<typename Map>
auto get_values(Map& map, const typename Map::key_type& key) {
auto [b, e] = map.equal_range(key);
// 返回一个可以用于范围for的简单包装
struct iterator_pair {
typename Map::iterator begin_, end_;
auto begin() { return begin_; }
auto end() { return end_; }
};
return iterator_pair{b, e};
}
// 使用: for (auto& elem : get_values(mm, 1)) { ... }
当然，更直接的方式是利用C++17的if初始化器配合结构化绑定来检查空范围：
if (auto [lower, upper] = mm.equal_range(key); lower != upper) {
// 至少存在一个匹配元素
for (; lower != upper; ++lower) {
process(*lower);
}
} else {
// 没有找到
}
这些模式避免了手动调用lower_bound和upper_bound的繁琐，而且equal_range内部通常可以优化为只进行一次树查找，比分别调用两次查找更高效。在multimap这样具有对数查找复杂度的容器中，尽量使用equal_range是一个良好的习惯。
equal_range与lower_bound/upper_bound的关系及内部实现
equal_range本质上等价于std::make_pair(lower_bound(key), upper_bound(key))。标准库实现通常会利用lower_bound和upper_bound各自进行一次二分查找，或者在某些优化的树结构中直接返回lower_bound并继续线性遍历到upper_bound。但无论如何，它的均摊复杂度依然是对数时间的。单独调用lower_bound和upper_bound需要两次查找，而equal_range可以向实现提供合并优化的机会，因此更推荐使用。
下面是一个使用lower_bound和upper_bound手动构建范围的对比代码：
auto lower = mm.lower_bound(1);
auto upper = mm.upper_bound(1);
for (auto it = lower; it != upper; ++it) { /* ... */ }
虽然上述代码效果与equal_range完全相同，但对upper_bound的调用意味着还需要一次从根节点出发的查找。在键不存在的情况下，lower和upper会指向同一个位置，表示空范围。而equal_range返回的两个迭代器都指向lower_bound位置，语义上也是一致的。因此，除非有特殊理由只想获取下界或上界，否则永远应该优先选择equal_range。
从性能角度看，std::multimap的查找操作是O(log N)的，而遍历该范围是O(K)的，其中K为匹配的元素数量。因此整体操作的时间成本为O(log N + K)，这已经是最优的了。如果希望将键范围提取到一个新的容器中进一步处理，可以直接使用迭代器对构造std::vector：std::vector<:pair std::string>> vec(lower, upper);，这在大范围数据移动时非常便利。
常见陷阱与最佳实践
第一个常见的误区是尝试通过返回的迭代器修改键值。由于multimap内部节点的键是const的，任何试图通过迭代器it->first赋值的行为都会触发编译错误。但值部分可以安全修改，比如it->second = new_value。如果确实需要修改键，唯一的方法是从容器中删除该元素后重新插入新键值的元素。务必注意，任何删除操作都会导致指向该元素的迭代器失效，所以在遍历范围时如果要擦除某些元素，应该使用it = mm.erase(it)并小心边界。
另一个陷阱是关于const正确性。当在一个const成员函数中操作multimap成员时，equal_range返回的类型是const_iterator对，这有利于只读遍历。但如果试图将其赋值给一个非const迭代器变量，会出现类型不匹配的编译错误。推荐使用auto来接收，让编译器自动推导正确的类型，从而避免这类问题。
最后，如果只是想判断某个键是否存在，而不关心具体值，使用count(key) > 0可能看起来更直接，但count在multimap上的复杂度是O(log N + K)，因为需要遍历计数。而equal_range(key).first != equal_range(key).second的成本只是两次迭代器比较，并不会遍历整个范围。最佳实践是：auto [lb, ub] = map.equal_range(key); bool exists = (lb != ub);，这就足够轻量。
总之，equal_range是处理std::multimap键范围不可或缺的工具，结合现代C++的结构化绑定和范围for，可以让代码既高效又富有表达力。掌握这些技巧，你将能够从容应对各类多值映射的遍历与查询需求。
std::multimapequal_range键范围修改时间：2026-08-12 11:49:19