C++ unordered_multiset Library - extract() Function

---

---

Description

The unordered_multiset::extract() function in C++ STL was introduced in C++17. It is used to extract a node from an unordered_multiset container. The function removes the element from the container and returns a node handle that contains the extracted value. After extraction, the extracted node is removed from the container and does not exist in the original unordered_multiset.

Syntax

Following is the syntax of unordered_multiset::extract() function −

// Extract by iterator
node_type extract(const_iterator position);

// Extract by key
node_type extract(const key_type& key);

// Extract by key-like object
template< class K >
node_type extract(K&& keyObj);

Parameters

The extract() function accepts a single parameter. It can be an iterator pointing to the element to be extracted or a key of the element we want to extract.

Return value

The extract() function returns a node handle that contains the extracted value. If the key is not found, it returns an empty node handle.

Exceptions

If an exception is thrown, the container remains unchanged.

Time complexity

The time complexity of unordered_multiset::extract() function is O(1) using an iterator. Using key, the average is O(1), and worst is O(N) due to hash collisions.

Examples of unordered_multiset::extract() Function

The following examples demonstrate the usage of unordered_multiset::extract() function in unordered multiset −

Extracting an Element by Iterator

Below is an example to extract an element (30) from an unordered_multiset nums using an iterator it with the unordered_multiset::extract() function. If there are duplicates of 30, then it will extract any random value of 30.

#include <iostream>
#include <unordered_set>
using namespace std;

int main() {
    unordered_multiset<int> nums = {10, 20, 30, 40, 50, 30};

    cout << "Unordered_multiset before extraction:";
    for (const auto &num : nums)
        cout << " " << num;
    cout << endl;

    auto it = nums.find(30);
    auto node = nums.extract(it);

    cout << "Extracted element: " << node.value() << endl;

    cout << "Unordered_multiset after extraction:";
    for (const auto &num : nums)
        cout << " " << num;
    cout << endl;

    return 0;
}

The output of the above code is given below −

Unordered_multiset before extraction: 50 40 30 30 20 10
Extracted element: 30
Unordered_multiset after extraction: 50 40 30 20 10

Extracting an Element by Key

In this example, we are extracting the element 20 from unordered_multiset nums using the key with the unordered_multiset::extract() function.

#include <iostream>
#include <unordered_set>
using namespace std;

int main() {
    unordered_multiset<int> nums = {10, 20, 20, 30, 40};

    cout << "Unordered_multiset before extraction:";
    for (const auto &num : nums)
        cout << " " << num;
    cout << endl;

    auto node = nums.extract(20);

    if (!node.empty()){
        cout << "Extracted element: " << node.value() << endl;
    }

    cout << "Unordered_multiset after extraction:";
    for (const auto &num : nums)
        cout << " " << num;
    cout << endl;

    return 0;
}

The output of the above code is given below −

Unordered_multiset before extraction: 10 20 20 30 40
Extracted element: 20
Unordered_multiset after extraction: 10 20 30 40

Moving Extracted Node to Another unordered_multiset

Here is an example to extract an element from one unordered_multiset um1 and insert it into another unordered_multiset um2 using unordered_multiset::extract() and insert() −

#include <iostream>
#include <unordered_set>
using namespace std;

int main() {
    unordered_multiset<int> um1 = {10, 20, 30, 40};
    unordered_multiset<int> um2 = {50, 60, 70};

    cout << "Unordered_multiset 1 before extraction:";
    for (const auto &num : um1)
        cout << " " << num;
    cout << endl;

    cout << "Unordered_multiset 2 before insertion:";
    for (const auto &num : um2)
        cout << " " << num;
    cout << endl;

    auto node = um1.extract(30);
    um2.insert(move(node));

    cout << "\nUnordered_multiset 1 after extraction:";
    for (const auto &num : um1)
        cout << " " << num;
    cout << endl;

    cout << "Unordered_multiset 2 after insertion:";
    for (const auto &num : um2)
        cout << " " << num;
    cout << endl;

    return 0;
}

The output of the above code is given below −

Unordered_multiset 1 before extraction: 10 20 30 40
Unordered_multiset 2 before insertion: 50 60 70

Unordered_multiset 1 after extraction: 10 20 40
Unordered_multiset 2 after insertion: 30 50 60 70

Run the above example codes in the compilers that supports C++17 and above.

Difference Between multiset::extract and unordered_multiset::extract

The differences between multiset::extract and unordered_multiset::extract functions are given below −