std::unorde...:equal_range(3)

🌸 NAME 🌸

Okay so the page title is std::unorde...:equal_range(3), and it comes from the C++ Standard Libary manual — and yes, bestie, “Libary” is spelled exactly like that in the header, we are leaving it alone 💅. The function itself is std::unordered_map::equal_range — literally std::unordered_map::equal_range, no notes, it's the range-grabbing bestie ✨.

---

✨ Synopsis ✨

Here's the overload lineup, and I'm obsessed:

(1) — since C++11:

std::pair<iterator, iterator> equal_range( const Key& key );

(2) — since C++11:

std::pair<const_iterator, const_iterator> equal_range( const Key& key ) const;

(3) — since C++20:

template< class K >
std::pair<iterator, iterator> equal_range( const K& x );

(4) — since C++20:

template< class K >
std::pair<const_iterator, const_iterator> equal_range( const K& x ) const;

So like, 1,2) returns a range containing all elements with key key in the container. That range is defined by two iterators: the first points to the first element of the wanted range, and the second points past the last element of the range. Periodt 💅.

And 3,4) returns a range containing all elements in the container with key equivalent to x. This overload participates in overload resolution only if Hash::is_transparent and KeyEqual::is_transparent are valid and each denotes a type. This assumes that such Hash is callable with both K and Key type, and that the KeyEqual is transparent, which, together, allows calling this function without constructing an instance of Key. No extra Key construction, highkey iconic 🎀.

---

🎀 Parameters 🎀

• key — key value to compare the elements to.
• x — a value of any type that can be transparently compared with a key.

---

💖 Return value 💖

A std::pair containing a pair of iterators defining the wanted range. If there are no such elements, past-the-end (see end()) iterators are returned as both elements of the pair. That's the whole vibe: no matches, both iterators are past-the-end 🫶.

---

🔥 Complexity 🔥

Average case linear in the number of elements with the key key, worst case linear in the size of the container. That's the tea, fr fr.

---

🧚 Notes 🧚

Feature-test macro tea ☕ — the receipts are:

• Feature-test macro: __cpp_lib_generic_unordered_lookup
• Value: 201811L
• Std: (C++20)
• Feature: Heterogeneous comparison lookup in unordered associative containers, overloads (3,4)

---

🌈 Example 🌈

Run this code, bestie:

// Run this code

#include <iostream>
#include <unordered_map>

int main()
{
    std::unordered_map<int,char> map = {{1, 'a'},{2, 'b'}};
    auto range = map.equal_range(1);
    for (auto it = range.first; it != range.second; ++it)
        std::cout << it->first << ' ' << it->second << '\n';
}

Output 💬

1 a

---

👀 See also 👀

The whole friend group:

• find — finds element with specific key; public member function.
• contains — checks if the container contains element with specific key; (C++20), public member function.
• count — returns the number of elements matching specific key; public member function.
• equal_range — returns range of elements matching a specific key; function template.

---

Okay that's the whole page, go be a main character with your iterators 🫶 — source: http://cppreference.com · version/date: 2024.06.10 · page: std::unorde...:equal_range(3)