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

NAME
     std::unordered_map - std::unordered_map

Synopsis
	Defined in header <unordered_map>
	template<

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

	> class unordered_map;
	namespace pmr {

	    template<
		class Key,
		class T,
		class Hash = std::hash<Key>,
		class KeyEqual =  std::equal_to<Key>			     (2)
     (since C++17)
	    > using unordered_map =
		  std::unordered_map<Key, T, Hash, KeyEqual,
		      std::pmr::polymorphic_allocator<std::pair<const Key,
	T>>>;

	}

	std::unordered_map  is	an associative container that contains key-value
     pairs with
	unique keys. Search, insertion, and removal  of  elements  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
	key. Keys with the same hash code appear in the same bucket. This allows
     fast access
	to individual elements, since once the hash is computed,  it  refers  to
     the exact
	bucket the element is placed into.

	Two  keys  are considered equivalent if the map's key equality predicate
     returns true
	when passed those keys. If two keys are equivalent,  the  hash	function
     must return
	the same value for both keys.

	std::unordered_map  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 either key or data stored in the con-
     tainer are only
	    invalidated by erasing that element, even when the corresponding it-
     erator is
	    invalidated.

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

Member types
	Member type		 Definition
	key_type		 Key
	mapped_type		 T
	value_type		 std::pair<const Key, T>
	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		 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_map
			  (public member function)
	destructor	  destructs the unordered_map
			  (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)
	insert_or_assign  inserts an element or assigns to the	current  element
     if the key
	(C++17) 	  already exists
			  (public member function)
	emplace 	  constructs element in-place
			  (public member function)
	emplace_hint	  constructs elements in-place using a hint
			  (public member function)
	try_emplace	  inserts in-place if the key does not exist, does noth-
     ing if the
	(C++17) 	  key exists
			  (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
	at		  access specified element with bounds checking
			  (public member function)
	operator[]	  access or insert specified element
			  (public member function)
	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_map
	(C++11) 		      (function template)
	(C++11)(removed in C++20)
	std::swap(std::unordered_map) specializes the std::swap algorithm
	(C++11) 		      (function template)
	erase_if(std::unordered_map)  erases all  elements  satisfying	specific
     criteria
	(C++20) 		      (function template)

	  Deduction guides (since C++17)

Notes
	    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 <string>
      #include <unordered_map>

      int main()
      {
	  // Create an unordered_map of three strings (that map to strings)
	  std::unordered_map<std::string, std::string> u =
	  {
	      {"RED", "#FF0000"},
	      {"GREEN", "#00FF00"},
	      {"BLUE", "#0000FF"}
	  };

	  // Helper lambda function to print key-value pairs
	  auto print_key_value = [](const auto& key, const auto& value)
	  {
	      std::cout << "Key:[" << key << "] Value:[" << value << "]\n";
	  };

	  std::cout << "Iterate and print key-value pairs of unordered_map,  be-
     ing\n"
		       "explicit with their types:\n";
	  for (const std::pair<const std::string, std::string>& n : u)
	      print_key_value(n.first, n.second);

	  std::cout  <<  "\nIterate and print key-value pairs using C++17 struc-
     tured binding:\n";
	  for (const auto& [key, value] : u)
	      print_key_value(key, value);

	  // Add two new entries to the unordered_map
	  u["BLACK"] = "#000000";
	  u["WHITE"] = "#FFFFFF";

	  std::cout << "\nOutput values by key:\n"
		       "The HEX of color RED is:[" << u["RED"] << "]\n"
		       "The HEX of color BLACK is:[" << u["BLACK"] << "]\n\n";

	  std::cout << "Use operator[] with non-existent key  to  insert  a  new
     key-value pair:\n";
	  print_key_value("new_key", u["new_key"]);

	  std::cout << "\nIterate and print key-value pairs, using `auto`;\n"
		       "new_key is now one of the keys in the map:\n";
	  for (const auto& n : u)
	      print_key_value(n.first, n.second);
      }

Possible output:
      Iterate and print key-value pairs of unordered_map, being
      explicit with their types:
      Key:[BLUE] Value:[#0000FF]
      Key:[GREEN] Value:[#00FF00]
      Key:[RED] Value:[#FF0000]

      Iterate and print key-value pairs using C++17 structured binding:
      Key:[BLUE] Value:[#0000FF]
      Key:[GREEN] Value:[#00FF00]
      Key:[RED] Value:[#FF0000]

      Output values by key:
      The HEX of color RED is:[#FF0000]
      The HEX of color BLACK is:[#000000]

      Use operator[] with non-existent key to insert a new key-value pair:
      Key:[new_key] Value:[]

      Iterate and print key-value pairs, using `auto`;
      new_key is now one of the keys in the map:
      Key:[new_key] Value:[]
      Key:[WHITE] Value:[#FFFFFF]
      Key:[BLACK] Value:[#000000]
      Key:[BLUE] Value:[#0000FF]
      Key:[GREEN] Value:[#00FF00]
      Key:[RED] Value:[#FF0000]

	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
	map collection of key-value pairs, sorted by keys, keys are unique
	    (class template)

Category:
	  * Todo with reason

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