Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::unorde...set::extract(3) C++ Standard Libarystd::unorde...set::extract(3)

NAME
       std::unordered_set::extract - std::unordered_set::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
	  Hash::is_transparent and KeyEqual::is_transparent are	valid and each
       denotes a type,
	  and  neither	iterator  nor const_iterator is	implicitly convertible
       from K. This
	  assumes that such Hash is callable with both K  and  Key  type,  and
       that the	KeyEqual
	  is  transparent, which, together, allows calling this	function with-
       out constructing
	  an instance of Key.

	  In either case, no elements are copied or moved, only	 the  internal
       pointers	of the
	  container nodes are repointed	.

	  Extracting  a	 node  invalidates only	the iterators to the extracted
       element,	and
	  preserves the	relative order of the elements that  are  not  erased.
       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 in-
       serted 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 Hash and KeyEqual object.

Complexity
	  1,2,3) Average case O(1), worst case O(a.size()).

Notes
	  extract is the only way to take a move-only object out of a set

	std::set<move_only_type> s;
	s.emplace(...);
	move_only_type mot = std::move(s.extract(s.begin()).value());

	  Feature-test macro: __cpp_lib_associative_heterogeneous_erasure (for
       overload	(3))

Example
       // Run this code

	#include <algorithm>
	#include <iostream>
	#include <string_view>
	#include <unordered_set>

	void print(std::string_view comment, const auto& data)
	{
	    std::cout << comment;
	    for	(auto datum : data)
		std::cout << ' ' << datum;

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

	int main()
	{
	    std::unordered_set<int> cont{1, 2, 3};

	    print("Start:", cont);

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

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

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

	    print("End:", cont);
	}

Possible output:
	Start: 1 2 3
	After extract and before insert: 2 3
	End: 2 3 4

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

http://cppreference.com		  2022.07.31	 std::unorde...set::extract(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::unordered_set::extract&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help