Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C++

Associative-container node handles

A node handle owns an element extracted from an associative container. It lets you modify its key and transfer the node to a compatible container without copying or moving the element itself. Correct use requires checking emptiness, allocator compatibility, and insertion results.

Version: C++23; repository compiler flag, production runtime not attested

Syntax

auto nh = source.extract(key);
if (nh) {
    nh.key() = new_key; // map-like containers
    auto result = destination.insert(std::move(nh));
    // Unique-key, non-hinted insertion: inspect result.inserted and result.node.
}

Associative-container node handles own individual extracted nodes from ordered and unordered associative containers. Spell the type as Container::node_type; the standard's node-handle is an exposition-only name, not a class named std::node_handle. extract(key) removes an element and returns its handle; a missing key produces an empty handle. Transferring a node neither copies nor moves the element itself.

A handle is movable but not copyable. empty() and operator bool() test its state. For maps, key() and mapped() expose the modifiable key and mapped value; for sets, use value(). These operations and get_allocator() require a nonempty handle. Destroying a nonempty handle destroys the element and deallocates the node's storage.

Compatibility covers the map/multimap and set/multiset families and their unordered_ counterparts, with matching key, mapped-value, and allocator types as applicable. Comparators, hash functions, or equality predicates may differ. Nodes cannot transfer this way between ordered and unordered families. When inserting a nonempty handle, its allocator must equal the destination allocator; violating this requirement causes undefined behavior.

For a unique-key container, non-hinted insert(std::move(nh)) returns fields position, inserted, and node. On a key collision, the rejected node belongs to result.node, not nh. The example recovers it, changes its key, and retries. The sources describe the current working draft; the example targets compilation with -std=c++23, without assuming production runtime support.

Examples

#include <iostream>
#include <map>
#include <string>
#include <utility>

int main() {
    std::map<int, std::string> source{{1, "Ada"}};
    std::map<int, std::string> destination{{2, "Grace"}};

    auto nh = source.extract(1);
    if (!nh) return 1;
    nh.key() = 2;

    auto result = destination.insert(std::move(nh));
    std::cout << std::boolalpha << "inserted: " << result.inserted << '\n';

    if (!result.inserted) {
        result.node.key() = 3;
        auto retry = destination.insert(std::move(result.node));
        if (!retry.inserted) return 2;
    }

    std::cout << "source size: " << source.size() << '\n';
    for (const auto& [key, name] : destination) {
        std::cout << key << ": " << name << '\n';
    }
}

Result

inserted: false
source size: 0
2: Grace
3: Ada

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources