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

NAME
     std::unordered_set - std::unordered_set

Synopsis
	Defined in header <unordered_set>
	template<

	    class Key,
	    class  Hash  = std::hash<Key>,				     (1)
     (since C++11)
	    class KeyEqual = std::equal_to<Key>,
	    class Allocator = std::allocator<Key>

	> class unordered_set;
	namespace pmr {

	    template<
		class Key,
		class Hash = std::hash<Key>,
		class Pred =  std::equal_to<Key>			     (2)
     (since C++17)
	    > using unordered_set = std::unordered_set<Key, Hash, Pred,

	std::pmr::polymorphic_allocator<Key>>;

	}

	std::unordered_set  is	an  associative container that contains a set of
     unique objects
	of type Key. Search, insertion, and removal have  average  constant-time
     complexity.

	Internally, the elements are not sorted in any particular order, but or-
     ganized into
	buckets.  Which bucket an element is placed into depends entirely on the
     hash of its
	value. This allows fast access to individual elements, since once a hash
     is
	computed, it refers to the exact bucket the element is placed into.

	Container elements may not be modified (even  by  non  const  iterators)
     since
	modification could change an element's hash and corrupt the container.

	std::unordered_set  meets the requirements of Container, AllocatorAware-
     Container,
	UnorderedAssociativeContainer.

Notes
	  * The swap functions do not invalidate any of the iterators inside the
     container,
	    but they do invalidate the iterator marking the end of the swap  re-
     gion.
	  * References and pointers to data stored in the container are only in-
     validated by
	    erasing that element, even when the corresponding iterator is inval-
     idated.
	  *  After container move assignment, unless elementwise move assignment
     is forced by
	    incompatible allocators, references, pointers, and iterators  (other
     than the
	    past-the-end iterator) to moved-from container remain valid, but re-
     fer to
	    elements that are now in *this.

Template parameters
	 This section is incomplete
	 Reason: Add descriptions of the template parameters.

Member types
	Member type		 Definition
	key_type		 Key
	value_type		 Key
	size_type		 Unsigned integer type (usually std::size_t)
	difference_type 	 Signed integer type (usually std::ptrdiff_t)
	hasher			 Hash
	key_equal		 KeyEqual
	allocator_type		 Allocator
	reference		 value_type&
	const_reference 	 const value_type&
	pointer 		 std::allocator_traits<Allocator>::pointer
	const_pointer		 std::allocator_traits<Allocator>::const_pointer
	iterator		 Constant LegacyForwardIterator to value_type
	const_iterator		 LegacyForwardIterator to const value_type
				 An iterator type whose category, value, differ-
     ence, pointer
				 and
	local_iterator		  reference types are the same as iterator. This
     iterator
				 can be used to iterate through a single  bucket
     but not
				 across buckets
				 An iterator type whose category, value, differ-
     ence, pointer
				 and
	const_local_iterator	 reference types are the same as const_iterator.
     This
				 iterator
				 can  be used to iterate through a single bucket
     but not
				 across buckets
	node_type (since C++17)  a specialization of node handle representing  a
     container
				 node
				 type  describing  the	result	of  inserting  a
     node_type, a
				 specialization of

				 template<class Iter, class NodeType>
				 struct /*unspecified*/
	insert_return_type	 {
	(since C++17)		     Iter     position;
				     bool     inserted;
				     NodeType node;
				 };
				 instantiated with template  arguments	iterator
     and
				 node_type.

Member functions
	constructor	  constructs the unordered_set
			  (public member function)
	destructor	  destructs the unordered_set
			  (public member function)
	operator=	  assigns values to the container
			  (public member function)
	get_allocator	  returns the associated allocator
			  (public member function)

Iterators
	begin		  returns an iterator to the beginning
	cbegin		  (public member function)
	end		  returns an iterator to the end
	cend		  (public member function)

Capacity
	empty		  checks whether the container is empty
			  (public member function)
	size		  returns the number of elements
			  (public member function)
	max_size	  returns the maximum possible number of elements
			  (public member function)

Modifiers
	clear		  clears the contents
			  (public member function)
			  inserts elements
	insert		  or nodes
			  (since C++17)
			  (public member function)
	insert_range	  inserts a range of elements
	(C++23) 	  (public member function)
	emplace 	  constructs element in-place
			  (public member function)
	emplace_hint	  constructs elements in-place using a hint
			  (public member function)
	erase		  erases elements
			  (public member function)
	swap		  swaps the contents
			  (public member function)
	extract 	  extracts nodes from the container
	(C++17) 	  (public member function)
	merge		  splices nodes from another container
	(C++17) 	  (public member function)

Lookup
	count		  returns the number of elements matching specific key
			  (public member function)
	find		  finds element with specific key
			  (public member function)
	contains	  checks if the container contains element with specific
     key
	(C++20) 	  (public member function)
	equal_range	  returns range of elements matching a specific key
			  (public member function)

Bucket interface
	begin(size_type)   returns an iterator to the beginning of the specified
     bucket
	cbegin(size_type) (public member function)
	end(size_type)	  returns an iterator to the end of the specified bucket
	cend(size_type)   (public member function)
	bucket_count	  returns the number of buckets
			  (public member function)
	max_bucket_count  returns the maximum number of buckets
			  (public member function)
	bucket_size	  returns the number of elements in specific bucket
			  (public member function)
	bucket		  returns the bucket for specific key
			  (public member function)

Hash policy
	load_factor	  returns average number of elements per bucket
			  (public member function)
	max_load_factor   manages maximum average number of elements per bucket
			  (public member function)
			  reserves at least the specified number of buckets  and
     regenerates
	rehash		  the hash table
			  (public member function)
			  reserves  space  for	at least the specified number of
     elements and
	reserve 	  regenerates the hash table
			  (public member function)

Observers
	hash_function	  returns function used to hash the keys
			  (public member function)
	key_eq		  returns the function used to compare keys for equality
			  (public member function)

Non-member functions
	operator==
	operator!=		      compares the values in the unordered_set
	(C++11) 		      (function template)
	(C++11)(removed in C++20)
	std::swap(std::unordered_set) specializes the std::swap algorithm
	(C++11) 		      (function template)
	erase_if(std::unordered_set)  erases all  elements  satisfying	specific
     criteria
	(C++20) 		      (function template)

	  Deduction guides (since C++17)

Notes
	The  member types iterator and const_iterator may be aliases to the same
     type. This
	means defining a pair of function overloads using the two types as para-
     meter types
	may violate the One Definition Rule. Since iterator is convertible to
	const_iterator, a single function with	a  const_iterator  as  parameter
     type will work
	instead.

	    Feature-test macro	     Value    Std		    Feature
	__cpp_lib_containers_ranges  202202L (C++23) Ranges construction and in-
     sertion for
						    containers

Example
     // Run this code

      #include <iostream>
      #include <unordered_set>

      void print(const auto& set)
      {
	  for (const auto& elem : set)
	      std::cout << elem << ' ';
	  std::cout << '\n';
      }

      int main()
      {
	  std::unordered_set<int> mySet{2, 7, 1, 8, 2, 8}; // creates a  set  of
     ints
	  print(mySet);

	  mySet.insert(5); // puts an element 5 in the set
	  print(mySet);

	  if (auto iter = mySet.find(5); iter != mySet.end())
	      mySet.erase(iter); // removes an element pointed to by iter
	  print(mySet);

	  mySet.erase(7); // removes an element 7
	  print(mySet);
      }

Possible output:
      8 1 7 2
      5 8 1 7 2
      8 1 7 2
      8 1 2

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to	     Behavior as published		 Correct
     behavior
			    the definitions of reference,
	LWG  2050  C++11       const_reference, pointer 		based on
     value_type and
			    and const_pointer were based on	      std::allo-
     cator_traits
			    allocator_type

See also
	set collection of unique keys, sorted by keys
	    (class template)

Category:
	  * Todo with reason

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