Defined in header
Defined in header
Defined in header
(since C++26)
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
Defined in header
template<classKey>structhash;(since C++11)The unordered associative containers
,
,
,
use specializations of the template std::hash as the default hash function.
Given a type Key, each specialization std::hash<Key> is either enabled or disabled :
If std::hash<Key> is not provided by the program or the user, it is disabled.
Otherwise, std::hash<Key> is enabled if all following conditions are satisfied:
All following requirements are satisfied:
(with Key as the function call argument type)
Given the following values:
h, an object of type std::hash<Key>.
k1 and k2, objects of type Key.
All following requirements are satisfied: If k1==k2 is true, h(k1)==h(k2) is also true.
Unless std::hash<Key> is a
program-defined specialization
, h(k1) will never throw an exception.
Otherwise, std::hash<Key> is disabled.
Disabled specializations do not satisfy
, do not satisfy
, and following values are all false:
std::is_default_constructible<std::hash<Key>>::value
std::is_copy_constructible<std::hash<Key>>::value
std::is_move_constructible<std::hash<Key>>::value
std::is_copy_assignable<std::hash<Key>>::value
std::is_move_assignable<std::hash<Key>>::value
In other words, they exist, but cannot be used.
Nested types
Type Definition argument_type(deprecated in C++17)Keyresult_type(deprecated in C++17)
(until C++20)Member functions
constructs a hash function object
(public member function)calculates the hash of the argument
(public member function)Standard library specializations
Each header that declares the template std::hash also provides enabled specializations of std::hash for the following types:
all cv-unqualified
all cv-unqualified
all cv-unqualified
On top of that, some headers also provide other enabled std::hash specializations for library types (see
).
Specializations for library types
Language support library
std::hash<std::coroutine_handle>
(C++20)
hash support for
(class template specialization)
Dianostics library
(C++11)
hash support for
(class template specialization)
std::hash<std::error_condition>
(C++17)
hash support for
(class template specialization)
(C++11)
hash support for
(class template specialization)
std::hash<std::stacktrace_entry>
(C++23)
hash support for
(class template specialization)
std::hash<std::basic_stacktrace>
(C++23)
hash support for
(class template specialization)
Memory management library
(C++11)
hash support for
(class template specialization)
(C++11)
hash support for
(class template specialization)
(C++26)
hash support for
(class template specialization)
General utilities library
(C++17)
hash support for
(class template specialization)
(C++17)
hash support for
(class template specialization)
(C++17)
hash support for
(class template specialization)
(C++11)
hash support for
(class template specialization)
Containers library
(C++11)
hash support for
(class template specialization) Strings library
(C++11)
hash support for strings
(class template specialization)
(C++17)(C++17)(C++20)(C++17)(C++17)
hash support for string views
(class template specialization)
Text processing library
(C++26)
hash support for
(class template specialization)
Time library
std::hash<std::chrono::duration>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::time_point>
(C++26)
hash support for
(class template specialization)
(C++26)
hash support for
(class template specialization)
(C++26)
hash support for
(class template specialization)
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::weekday>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::weekday_indexed>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::weekday_last>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::month_day>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::month_day_last>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::month_weekday>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::month_weekday_last>
(C++26)
hash support for
std::chrono::month_weekday_last
(class template specialization)
std::hash<std::chrono::year_month>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::year_month_day>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::year_month_day_last>
(C++26)
hash support for
std::chrono::year_month_day_last
(class template specialization)
std::hash<std::chrono::year_month_weekday>
(C++26)
hash support for
std::chrono::year_month_weekday
(class template specialization)
std::hash<std::chrono::year_month_weekday_last>
(C++26)
hash support for
std::chrono::year_month_weekday_last
(class template specialization)
std::hash<std::chrono::zoned_time>
(C++26)
hash support for
(class template specialization)
std::hash<std::chrono::leap_second>
(C++26)
hash support for
(class template specialization)Notes
The actual hash functions are implementation-dependent and are not required to fulfill any other quality criteria except those specified above. Notably, some implementations use trivial (identity) hash functions which map an integer to itself. In other words, these hash functions are designed to work with unordered associative containers, but not as cryptographic hashes, for example.
Hash functions are only required to produce the same result for the same input within a single execution of a program; this allows salted hashes that prevent collision denial-of-service attacks.
There is no specialization for C strings. std::hash<constchar*> produces a hash of the value of the pointer (the memory address), it does not examine the contents of any character array.
Additional specializations for
and the standard container types, as well as utility functions to compose hashes are available in
.
Example
Run this code
#include<cstddef>#include<functional>#include<iomanip>#include<iostream>#include<string>#include<unordered_set>structS{std::stringfirst_name;std::stringlast_name;booloperator==(constS&)const=default;// since C++20};// Before C++20.// bool operator==(const S& lhs, const S& rhs)// {// return lhs.first_name == rhs.first_name && lhs.last_name == rhs.last_name;// }// Custom hash can be a standalone function object.structMyHash{std::size_toperator()(constS&s)constnoexcept{std::size_th1=std::hash<std::string>{}(s.first_name);std::size_th2=std::hash<std::string>{}(s.last_name);returnh1^(h2<<1);// or use boost::hash_combine}};// Custom specialization of std::hash can be injected in namespace std.template<>structstd::hash<S>{std::size_toperator()(constS&s)constnoexcept{std::size_th1=std::hash<std::string>{}(s.first_name);std::size_th2=std::hash<std::string>{}(s.last_name);returnh1^(h2<<1);// or use boost::hash_combine}};intmain(){std::stringstr="Meet the new boss...";std::size_tstr_hash=std::hash<std::string>{}(str);std::cout<<"hash("<<std::quoted(str)<<") =\t"<<str_hash<<'\n';Sobj={"Hubert","Farnsworth"};// Using the standalone function object.std::cout<<"hash("<<std::quoted(obj.first_name)<<", "<<std::quoted(obj.last_name)<<") =\t"<<MyHash{}(obj)<<" (using MyHash) or\n\t\t\t\t"<<std::hash<S>{}(obj)<<" (using injected specialization)\n";// Custom hash makes it possible to use custom types in unordered containers.// The example will use the injected std::hash<S> specialization above,// to use MyHash instead, pass it as a second template argument.std::unordered_set<S>names={obj,{"Bender","Rodriguez"},{"Turanga","Leela"}};for(autoconst&s:names)std::cout<<std::quoted(s.first_name)<<' '<<std::quoted(s.last_name)<<'\n';}Possible output:
hash("Meet the new boss...") = 10656026664466977650 hash("Hubert", "Farnsworth") = 12922914235676820612 (using MyHash) or 12922914235676820612 (using injected specialization) "Bender" "Rodriguez" "Turanga" "Leela" "Hubert" "Farnsworth" Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++11 specializations for extended integer types were missing provided
C++11 specializations for enumerations were missing provided
C++11 std::hash might not be SFINAE-friendly made SFINAE-friendly
C++11 specialization for
was missing provided