Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Memory and Utilities

C++ std::hash class template

Reference for std::hash: hash built-in types and strings, write a custom specialization for unordered containers, and combine member hashes safely.

std::hash<T> (header <functional>, with specializations also declared in the headers of their types) is a function object that maps a value of type T to a std::size_t hash code. The unordered containers, std::unordered_map, std::unordered_set and their multi variants, use it by default to decide which bucket an element belongs to.

The standard provides specializations for integers, floating-point types, pointers, bool, char types, enumerations, std::string and the other string types, std::string_view, std::unique_ptr, std::shared_ptr, std::optional, std::bitset, std::thread::id and a few more. For your own types you add a specialization or pass your own hasher to the container.

C++
std::hash<std::string> h;
std::size_t code = h("hello");   // some size_t value

Try it

C++ Using the built-in hashers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Custom type in an unordered_set

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
template<class Key> struct hash;      // primary template: disabled unless specialized

// every enabled specialization provides:
std::size_t operator()(const Key& key) const noexcept(/* usually */);
Name Description
Key The type to hash. Must be usable as an argument for operator().
key The value to hash.

Returns: a std::size_t hash code.

Requirements for a valid hash: the result depends only on the argument, equal values (by the container's equality predicate) must have equal hashes, and the function must not throw for the container operations that need it. Different values should rarely collide.

Errors / undefined behavior: using std::unordered_set<T> with a T that has no enabled std::hash<T> is a compile error. A hash that violates the equality rule (equal keys, different hashes) breaks the container: lookups can miss elements that are present.

Usage notes

  • Values are not portable. The numbers differ between standard libraries, versions and sometimes runs. Never store them in files, send them over a network or print them in tests.
  • Integers often hash to themselves in libstdc++, which is fine for hash tables but not for security. Hash flooding attacks apply to public input; use a keyed hash for that.
  • Pointers hash by address; two different pointers to equal values hash differently. std::hash<const char*> hashes the pointer, not the characters. Use std::string_view for text.
  • Custom specializations go in the std namespace as template <> struct std::hash<MyType>; you may specialize only for your own types.
  • Combining fields: XOR alone makes Point{1,2} and Point{2,1} collide. Mix with shifts and constants as in the example, or use a helper that your project standardizes. The standard has no hash_combine.
  • Alternative to specializing: pass a hasher as the second template argument of the container, which also lets you hash a type you do not own.
  • Transparent hashing (C++20) lets unordered_map<string, V> look up with string_view without creating a string, when you provide a hasher with is_transparent.
  • Consistency with ==. If your operator== ignores a field, your hash must ignore it too.
  • Floating-point: 0.0 and -0.0 compare equal and hash equal; NaN never compares equal to itself, so it makes a poor key.