std::hash

 

C++

Compiler-Unterstützung

Freestanding und gehostet

Sprache

Standardbibliothek

Header der Standardbibliothek

Benannte Anforderungen

Feature-Test-Makros (C++20)

Bibliothek für Sprachunterstützung

Konzepte-Bibliothek (C++20)

Diagnostik-Bibliothek

Speicherverwaltungsbibliothek

Metaprogrammierungsbibliothek (C++11)

Allgemeine Dienstprogramme-Bibliothek

Container-Bibliothek

Iterator-Bibliothek

Ranges-Bibliothek (C++20)

Algorithmen-Bibliothek

Bibliothek für Zeichenketten

Textverarbeitungsbibliothek

Numerik-Bibliothek

Datums- und Zeitbibliothek

Ein-/Ausgabe-Bibliothek

Dateisystembibliothek (C++17)

Unterstützung für nebenläufige Programmierung (C++11)

Ausführungssteuerungsbibliothek (C++26)

Technische Spezifikationen

Symbolverzeichnis

Externe Bibliotheken

 

Dienstprogramm-Bibliotheken

Sprachunterstützung Typunterstützung (Basistypen, RTTI) Bibliotheks-Feature-Test-Makros (C++20) Programm-Dienstprogramme Variadische Funktionen initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) Coroutine-Unterstützung (C++20) Vertragsunterstützung (C++26) Drei-Wege-Vergleich three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

Allgemeine Hilfsmittel Funktionsobjekte Bit-Manipulation (C++20) bitset hash (C++11) Relationale Operatoren (in C++20 veraltet) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Ganzzahl-Vergleichsfunktionen cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap und Typ-Operationen swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Gemeinsame Vokabulartypen pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

std::hash

hash::hash

hash::operator()

 

Definiert in der Header-Datei <bitset>
Definiert in Header <coroutine>
Definiert in Header <chrono>		(seit C++26)
Definiert in Header <filesystem>
Definiert in der Header-Datei <functional>
Definiert in Header <memory>
Definiert in der Header-Datei <optional>
Definiert in der Header-Datei <stacktrace>
Definiert in Header <string>
Definiert in Header <string_view>
Definiert in der Header-Datei <system_error>
Definiert in Header <text_encoding>
Definiert in Header <thread>
Definiert in Header <typeindex>
Definiert in der Header-Datei <variant>
Definiert in Header <vector>
template< class Key > struct hash;		(seit C++11)

Die ungeordneten assoziativen Container std::unordered_set, std::unordered_multiset, std::unordered_map, std::unordered_multimap verwenden Spezialisierungen der Template-Klasse std::hash als Standard-Hashfunktion.

Gegeben einen Typ Key, ist jede Spezialisierung std::hash<Key> entweder *aktiviert* oder *deaktiviert*.

• Wenn std::hash<Key> nicht vom Programm oder vom Benutzer bereitgestellt wird, ist sie deaktiviert.
• Andernfalls ist std::hash<Key> aktiviert, wenn alle folgenden Bedingungen erfüllt sind:

• Alle folgenden Anforderungen sind erfüllt:

• Hash (wobei Key der Typ des Funktionsaufrufarguments ist)
• DefaultConstructible
• CopyAssignable
• Swappable

• Gegeben die folgenden Werte:

• h, ein Objekt vom Typ std::hash<Key>.
• k1 und k2, Objekte vom Typ Key.

Alle folgenden Anforderungen sind erfüllt:

• Wenn k1 == k2 true ist, dann ist auch h(k1) == h(k2) true.
• Sofern std::hash<Key> keine programmdirekte Spezialisierung ist, wirft h(k1) niemals eine Ausnahme.

• Andernfalls ist std::hash<Key> deaktiviert.

Deaktivierte Spezialisierungen erfüllen nicht die Anforderung Hash, erfüllen nicht die Anforderung FunctionObject, und die folgenden Werte sind alle 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

Mit anderen Worten, sie existieren, können aber nicht verwendet werden.

Verschachtelte Typen Name Definition argument_type (veraltet in C++17) Key result_type (veraltet in C++17) std::size_t

(bis C++20)

Memberfunktionen

(Konstruktor)	Erstellt ein Hash-Funktionsobjekt. (öffentliche Memberfunktion)
operator()	Berechnet den Hash des Arguments. (öffentliche Memberfunktion)

Standardbibliotheks-Spezialisierungen

Jeder Header, der die Template-Klasse std::hash deklariert, stellt auch aktivierte Spezialisierungen von std::hash für die folgenden Typen bereit:

• Alle cv-unqualifizierten arithmetischen Typen
• Alle cv-unqualifizierten Aufzählungstypen
• Alle cv-unqualifizierten Zeigertypen
• std::nullptr_t

Darüber hinaus stellen einige Header weitere aktivierte std::hash-Spezialisierungen für Bibliothekstypen bereit (siehe unten).

Für alle von der Standardbibliothek bereitgestellten std::hash-Spezialisierungen, mit Ausnahme der folgenden, sind alle ihre Memberfunktionen noexcept: std::hash<std::optional> std::hash<std::variant> std::hash<std::unique_ptr> std::hash<std::chrono::duration> std::hash<std::chrono::time_point> std::hash<std::chrono::zoned_time> (seit C++26)

(seit C++17)

Spezialisierungen für Bibliothekstypen

std::hash<std::coroutine_handle> (C++20)	Hash-Unterstützung für std::coroutine_handle (Klassentemplate-Spezialisierung)
std::hash<std::error_code> (C++11)	Hash-Unterstützung für std::error_code (Klassentemplate-Spezialisierung)
std::hash<std::error_condition> (C++17)	Hash-Unterstützung für std::error_condition (Klassentemplate-Spezialisierung)
std::hash<std::stacktrace_entry> (C++23)	Hash-Unterstützung für std::stacktrace_entry (Klassentemplate-Spezialisierung)
std::hash<std::basic_stacktrace> (C++23)	Hash-Unterstützung für std::basic_stacktrace (class template specialization)
std::hash<std::optional> (C++17)	Hash-Unterstützung für std::optional (Klassentemplate-Spezialisierung)
std::hash<std::variant> (C++17)	Hash-Unterstützung für std::variant (Klassentemplate-Spezialisierung)
std::hash<std::monostate> (C++17)	Hash-Unterstützung für std::monostate (Klassentemplate-Spezialisierung)
std::hash<std::bitset> (C++11)	Hash-Unterstützung für std::bitset (Klassentemplate-Spezialisierung)
std::hash<std::unique_ptr> (C++11)	Hash-Unterstützung für std::unique_ptr (Klassentemplate-Spezialisierung)
std::hash<std::shared_ptr> (C++11)	Hash-Unterstützung für std::shared_ptr (Klassentemplate-Spezialisierung)
std::hash<std::type_index> (C++11)	Hash-Unterstützung für std::type_index (Klassentemplate-Spezialisierung)
std::hash<std::basic_string> (C++11)	Hash-Unterstützung für Strings (Klassentemplate-Spezialisierung)
std::hash<std::string_view>std::hash<std::wstring_view>std::hash<std::u8string_view>std::hash<std::u16string_view>std::hash<std::u32string_view> (C++17)(C++17)(C++20)(C++17)(C++17)	Hash-Unterstützung für String-Views (Klassentemplate-Spezialisierung)
std::hash<std::text_encoding> (C++26)	Hash-Unterstützung für std::text_encoding (Klassentemplate-Spezialisierung)
std::hash<std::vector<bool>> (C++11)	Hash-Unterstützung für std::vector<bool> (Klassentemplate-Spezialisierung)
std::hash<std::filesystem::path> (C++17)	Hash-Unterstützung für std::filesystem::path (Klassentemplate-Spezialisierung)
std::hash<std::thread::id> (C++11)	Hash-Unterstützung für std::thread::id (Klassentemplate-Spezialisierung)
std::hash<std::chrono::duration> (C++26)	Hash-Unterstützung für std::chrono::duration (Klassentemplate-Spezialisierung)
std::hash<std::chrono::time_point> (C++26)	Hash-Unterstützung für std::chrono::time_point (Klassentemplate-Spezialisierung)
std::hash<std::chrono::day> (C++26)	Hash-Unterstützung für std::chrono::day (Klassentemplate-Spezialisierung)
std::hash<std::chrono::month> (C++26)	Hash-Unterstützung für std::chrono::month (Klassentemplate-Spezialisierung)
std::hash<std::chrono::year> (C++26)	Hash-Unterstützung für std::chrono::year (Klassentemplate-Spezialisierung)
std::hash<std::chrono::weekday> (C++26)	Hash-Unterstützung für std::chrono::weekday (Klassentemplate-Spezialisierung)
std::hash<std::chrono::weekday_indexed> (C++26)	Hash-Unterstützung für std::chrono::weekday_indexed (Klassentemplate-Spezialisierung)
std::hash<std::chrono::weekday_last> (C++26)	Hash-Unterstützung für std::chrono::weekday_last (Klassentemplate-Spezialisierung)
std::hash<std::chrono::month_day> (C++26)	Hash-Unterstützung für std::chrono::month_day (Klassentemplate-Spezialisierung)
std::hash<std::chrono::month_day_last> (C++26)	Hash-Unterstützung für std::chrono::month_day_last (Klassentemplate-Spezialisierung)
std::hash<std::chrono::month_weekday> (C++26)	Hash-Unterstützung für std::chrono::month_weekday (Klassentemplate-Spezialisierung)
std::hash<std::chrono::month_weekday_last> (C++26)	Hash-Unterstützung für std::chrono::month_weekday_last (Klassentemplate-Spezialisierung)
std::hash<std::chrono::year_month> (C++26)	Hash-Unterstützung für std::chrono::year_month (Klassentemplate-Spezialisierung)
std::hash<std::chrono::year_month_day> (C++26)	Hash-Unterstützung für std::chrono::year_month_day (Klassentemplate-Spezialisierung)
std::hash<std::chrono::year_month_day_last> (C++26)	Hash-Unterstützung für std::chrono::year_month_day_last (Klassentemplate-Spezialisierung)
std::hash<std::chrono::year_month_weekday> (C++26)	Hash-Unterstützung für std::chrono::year_month_weekday (Klassentemplate-Spezialisierung)
std::hash<std::chrono::year_month_weekday_last> (C++26)	Hash-Unterstützung für std::chrono::year_month_weekday_last (Klassentemplate-Spezialisierung)
std::hash<std::chrono::zoned_time> (C++26)	Hash-Unterstützung für std::chrono::zoned_time (Klassentemplate-Spezialisierung)
std::hash<std::chrono::leap_second> (C++26)	Hash-Unterstützung für std::chrono::leap_second (Klassentemplate-Spezialisierung)

Hinweise

Die tatsächlichen Hash-Funktionen sind implementierungsabhängig und müssen keine anderen Qualitätskriterien erfüllen als die oben genannten. Insbesondere verwenden einige Implementierungen triviale (identitätsbehaftete) Hash-Funktionen, die eine ganze Zahl auf sich selbst abbilden. Anders ausgedrückt: Diese Hash-Funktionen sind dafür ausgelegt, mit ungeordneten assoziativen Containern zu funktionieren, aber nicht beispielsweise als kryptografische Hashes.

Hash-Funktionen müssen nur innerhalb einer einzigen Programmausführung dasselbe Ergebnis für denselben Input liefern. Dies ermöglicht "gesalzene" Hashes, die Angriffe durch Kollisions-Denial-of-Service verhindern.

Es gibt keine Spezialisierung für C-Strings. std::hash<const char*> erzeugt einen Hash des Zeigerwerts (der Speicheradresse); er untersucht nicht den Inhalt eines Zeichenarrays.

Zusätzliche Spezialisierungen für std::pair und die Standard-Container-Typen sowie Hilfsfunktionen zum Kombinieren von Hashes sind in boost::hash verfügbar.

Beispiel

Führen Sie diesen Code aus

#include <cstddef>
#include <functional>
#include <iomanip>
#include <iostream>
#include <string>
#include <unordered_set>
 
struct S
{
    std::string first_name;
    std::string last_name;
    bool operator==(const S&) 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.
struct MyHash
{
    std::size_t operator()(const S& s) const noexcept
    {
        std::size_t h1 = std::hash<std::string>{}(s.first_name);
        std::size_t h2 = std::hash<std::string>{}(s.last_name);
        return h1 ^ (h2 << 1); // or use boost::hash_combine
    }
};
 
// Custom specialization of std::hash can be injected in namespace std.
template<>
struct std::hash<S>
{
    std::size_t operator()(const S& s) const noexcept
    {
        std::size_t h1 = std::hash<std::string>{}(s.first_name);
        std::size_t h2 = std::hash<std::string>{}(s.last_name);
        return h1 ^ (h2 << 1); // or use boost::hash_combine
    }
};
 
int main()
{
    std::string str = "Meet the new boss...";
    std::size_t str_hash = std::hash<std::string>{}(str);
    std::cout << "hash(" << std::quoted(str) << ") =\t" << str_hash << '\n';
 
    S obj = {"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 (auto const& s: names)
        std::cout << std::quoted(s.first_name) << ' '
                  << std::quoted(s.last_name) << '\n';
}

Mögliche Ausgabe

hash("Meet the new boss...") =  10656026664466977650
hash("Hubert", "Farnsworth") =  12922914235676820612 (using MyHash) or
                                12922914235676820612 (using injected specialization)
"Bender" "Rodriguez"
"Turanga" "Leela"
"Hubert" "Farnsworth"

Fehlerberichte

Die folgenden Verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR	angewendet auf	Verhalten wie veröffentlicht	Korrigiertes Verhalten
LWG 2119	C++11	Spezialisierungen für erweiterte Integer-Typen fehlten.	bereitgestellt
LWG 2148	C++11	Spezialisierungen für Aufzählungstypen fehlten.	bereitgestellt
LWG 2543	C++11	std::hash war möglicherweise nicht SFINAE-freundlich.	Wurde SFINAE-freundlich gemacht.
LWG 2817	C++11	Spezialisierung für std::nullptr_t fehlte.	bereitgestellt