home | help 
std::map::extract(3)	       C++ Standard Libary	    std::map::extract(3)

NAME
     std::map::extract - std::map::extract

Synopsis
	node_type extract( const_iterator position ); (1) (since C++17)
	node_type extract( const Key& k );	      (2) (since C++17)
	template< class K >			      (3) (since C++23)
	node_type extract( K&& x );

	1) Unlinks the node that contains the element pointed to by position and
     returns a
	node handle that owns it.
	2) If the container has an element with key equivalent to k, unlinks the
     node that
	contains  that element from the container and returns a node handle that
     owns it.
	Otherwise, returns an empty node handle.
	3) Same as (2). This overload participates in overload	resolution  only
     if the
	qualified-id  Compare::is_transparent  is  valid and denotes a type, and
     neither
	iterator nor const_iterator is implicitly convertible from K. It  allows
     calling this
	function without constructing an instance of Key.

	In  either  case,  no  elements  are  copied or moved, only the internal
     pointers of the
	container nodes are repointed (rebalancing may occur, as with erase()).

	Extracting a node invalidates only the iterators to the  extracted  ele-
     ment. Pointers
	and references to the extracted element remain valid, but cannot be used
     while
	element  is owned by a node handle: they become usable if the element is
     inserted
	into a container.

Parameters
	position - a valid iterator into this container
	k	 - a key to identify the node to be extracted
	x	 - a value of any type that can be transparently compared with a
     key
		   identifying the node to be extracted

Return value
	A node handle that owns the extracted element, or empty node  handle  in
     case the
	element is not found in (2,3).

Exceptions
	1) Throws nothing.
	2,3) Any exceptions thrown by the Compare object.

Complexity
	1) Amortized constant.
	2,3) log(size())

Notes
	extract is the only way to change a key of a map element without reallo-
     cation:

      std::map<int, std::string> m{{1, "mango"}, {2, "papaya"}, {3, "guava"}};
      auto nh = m.extract(2);
      nh.key() = 4;
      m.insert(std::move(nh));
      // m == {{1, "mango"}, {3, "guava"}, {4, "papaya"}}

		    Feature-test macro		     Value    Std	    Fea-
     ture
								    Heteroge-
     neous erasure in
								    associative
     containers
	__cpp_lib_associative_heterogeneous_erasure   202110L  (C++23)	and  un-
     ordered
								    associative
     containers,
								    (3)

Example
     // Run this code

      #include <algorithm>
      #include <iostream>
      #include <string_view>
      #include <map>

      void print(std::string_view comment, const auto& data)
      {
	  std::cout << comment;
	  for (auto [k, v] : data)
	      std::cout << ' ' << k << '(' << v << ')';

	  std::cout << '\n';
      }

      int main()
      {
	  std::map<int, char> cont{{1, 'a'}, {2, 'b'}, {3, 'c'}};

	  print("Start:", cont);

	  // Extract node handle and change key
	  auto nh = cont.extract(1);
	  nh.key() = 4;

	  print("After extract and before insert:", cont);

	  // Insert node handle back
	  cont.insert(std::move(nh));

	  print("End:", cont);
      }

Output:
      Start: 1(a) 2(b) 3(c)
      After extract and before insert: 2(b) 3(c)
      End: 2(b) 3(c) 4(a)

See also
	merge	splices nodes from another container
	(C++17) (public member function)
		inserts elements
	insert	or nodes
		(since C++17)
		(public member function)
	erase	erases elements
		(public member function)

http://cppreference.com 	   2024.06.10		    std::map::extract(3)
home | help