std::set::equal_range(3)

💅 std::set::equal_range(3) — the C++ Standard Library, bestie edition 🎀

okay so picture this: it's a page about std::set::equal_range from the C++ Standard Library, and it's honestly kind of iconic. it hands you back a whole range of stuff that matches a key you give it. no cap. let's get into it ✨

---

✨ NAME ✨

std::set::equal_range — literally just std::set::equal_range, she's that girl, she contains multitudes 🫶

---

🌸 SYNOPSIS 🌸

here's the whole lineup, keep up:

     std::pair<iterator, iterator> equal_range( const Key& key );
  (1)
     std::pair<const_iterator, const_iterator> equal_range( const Key&
  (2)
     key ) const;
     template< class K >
  (3) (since C++14)
     std::pair<iterator, iterator> equal_range( const K& x );
     template< class K >
     std::pair<const_iterator, const_iterator> equal_range( const K& x
  (4) (since C++14)
     ) const;

so what she does: she returns a range containing all the elements with the given key in the container. the range is defined by two iterators — one pointing to the first element that is not less than key, and another pointing to the first element greater than key. 💖

alternatively (and this is the lowkey genius part), the first iterator may be obtained with lower_bound(), and the second with upper_bound(). iykyk.

• 1,2) compares the keys to key.
• 3,4) compares the keys to the value x. this overload participates in overload resolution only if the qualified-id Compare::is_transparent is valid and denotes a type. it allows calling this function without constructing an instance of Key. fancy, right? 💅

---

🦋 PARAMETERS 🦋

• key — key value to compare the elements to
• x — alternative value that can be compared to Key

---

🎀 RETURN VALUE 🎀

a std::pair containing a pair of iterators defining the wanted range: the first pointing to the first element that is not less than key, and the second pointing to the first element greater than key. 🫶

and now the part you need to remember, bestie:

if there are no elements not less than key, past-the-end (see end()) iterator is returned as the first element. similarly, if there are no elements greater than key, past-the-end iterator is returned as the second element.

like, she's not gonna invent an element for you. she just points at the end and goes "that's all, babe" 😭

---

💀 COMPLEXITY 💀

logarithmic in the size of the container. ngl, she's fast. ⚡

---

🧚 NOTES 🧚

okay there's this cute little feature-test macro table situation, let me lay it out for you:

• Feature-test macro: __cpp_lib_generic_associative_lookup
• Value: 201304L
• Std: (C++14)
• Feature: Heterogeneous comparison lookup in associative containers, for overloads (3,4)

see? heterogeneous comparison lookup in associative containers, for overloads (3,4). slay. 🔥

---

🌈 EXAMPLE 🌈

// Run this code — ok now look at this gorgeous little program:

    #include <iostream>
    #include <set>

    template<typename I>
    void print_equal_range(I first, I lb, I ub, I last)
    {
        for (I i{first}; i != lb; ++i)
            std::cout << *i << ' ';
        std::cout << "[ ";

        for (I i{lb}; i != ub; ++i)
            std::cout << *i << ' ';
        std::cout << ") ";

        for (I i{ub}; i != last; ++i)
            std::cout << *i << ' ';
        std::cout << '\n';
    }

    int main()
    {
        std::set<int> c{4, 3, 2, 1, 3, 3};
        std::cout << "c = ";
        print_equal_range(begin(c), begin(c), end(c), end(c));
        for (int key{}; key != 6; ++key)
        {
            std::cout << "key = " << key << "; equal range = ";
            const auto [lb, ub] = c.equal_range(key);
            print_equal_range(begin(c), lb, ub, end(c));
        }
    }

⭐ Output ⭐

and she prints, verbatim, no edits:

    c = [ 1 2 3 4 )
    key = 0; equal range = [ ) 1 2 3 4
    key = 1; equal range = [ 1 ) 2 3 4
    key = 2; equal range = 1 [ 2 ) 3 4
    key = 3; equal range = 1 2 [ 3 ) 4
    key = 4; equal range = 1 2 3 [ 4 )
    key = 5; equal range = 1 2 3 4 [ )

look at those brackets doing their little bracket dance. obsessed. 😻

---

👑 SEE ALSO 👑

your little circle of friends, all public member functions unless noted:

• 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)
• upper_bound — returns an iterator to the first element greater than the given key (public member function)
• lower_bound — returns an iterator to the first element not less than the given key (public member function)
• equal_range — returns range of elements matching a specific key (function template)

---

💜 and that's the whole page, bestie. this one came from http://cppreference.com, dated 2024.06.10, and it's page std::set::equal_range(3). mwah, go forth and query your sets with confidence. periodt. 💅✨