std::multimap::find(3)

🎀 NAME 🎀

std::multimap::find — literally std::multimap::find, bestie. This is the std::multimap::find(3) page from the C++ Standard Libary manual (yes, that's the header spelling, iykyk), and it's here to help you find stuff in a std::multimap without losing your mind. 💅

🦋 Synopsis 🦋

iterator find( const Key& key );             (1)
const_iterator find( const Key& key ) const; (2)
template< class K >                          (3) (since C++14)
iterator find( const K& x );
template< class K >                          (4) (since C++14)
const_iterator find( const K& x ) const;

Okay so here's the tea: 1,2) find an element with key equivalent to key. If there are several elements with the requested key in the container, any of them may be returned — do not assume a specific one, no cap. 🫶

3,4) find an element with key that compares equivalent 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. That's the transparent lookup slay. ✨

🌸 Parameters 🌸

• key — key value of the element to search for. 🔍
• x — a value of any type that can be transparently compared with a key. 🦋

💜 Return value 💜

An iterator to the requested element. If no such element is found, past-the-end (see end()) iterator is returned. So if your search hits the end, that's the "not found" vibe. 😭

✨ Complexity ✨

Logarithmic in the size of the container. Literally iconic efficiency. 👑

🫶 Notes 🫶

Feature-test macro tea, bestie:

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

🔥 Example 🔥

       // Run this code

        #include <iostream>
        #include <map>

        struct LightKey
        {
            int x;
        };

        struct FatKey
        {
            int x;
            int data[1000]; // a heavy blob
        };

        // As detailed above, the container must use std::less<> (or other
       transparent
        // Comparator) to access these overloads. This includes standard
       overloads,
        // such as comparison between std::string and std::string_view.
        bool operator<(const FatKey& fk, const LightKey& lk) { return fk.x <
       lk.x; }
        bool operator<(const LightKey& lk, const FatKey& fk) { return lk.x <
       fk.x; }
        bool operator<(const FatKey& fk1, const FatKey& fk2) { return fk1.x <
       fk2.x; }

        int main()
        {
            // Simple comparison demo.
            std::multimap<int, char> example{{1,'a'}, {2,'b'}};

            if (auto search = example.find(2); search != example.end())
                std::cout << "Found " << search->first << ' ' << search->second
       << '\n';
            else
                std::cout << "Not found\n";

            // Transparent comparison demo.
            std::multimap<FatKey, char, std::less<>> example2{{{1, {}}, 'a'},
       {{2, {}}, 'b'}};

            LightKey lk = {2};
            if (auto search = example2.find(lk); search != example2.end())
                std::cout << "Found " << search->first.x << ' ' <<
       search->second << '\n';
            else
                std::cout << "Not found\n";

            // Obtaining const iterators.
            // Compiler decides whether to return iterator of (non) const type
       by way of
            // accessing map; to prevent intentional modification, one of the
       simplest
            // options is to access the map via a constant reference.
            const auto& example2ref = example2;
            if (auto search = example2ref.find(lk); search != example2.end())
            {
                std::cout << "Found " << search->first.x << ' ' <<
       search->second << '\n';
            //  search->second = 'c'; // error: assignment of member
                                      // 'std::pair<const FatKey,
       char>::second'
                                      // in read-only object
            }
        }

Output:

Found 2 b
Found 2 b
Found 2 b

👑 See also 👑

• count — returns the number of elements matching specific key (public member function). 🔢
• equal_range — returns range of elements matching a specific key (public member function). 🌈

mwah 💖 that's the whole page! Source/version: http://cppreference.com, dated 2024.06.10, and it's the std::multimap::find(3) cutie. periodt ✨