std:: hash

Les spécialisations activées du modèle hash définissent un objet fonction qui implémente une fonction de hachage .

Étant donné un type Key , chaque spécialisation std::hash<Key> est soit activée soit désactivée  :

• Si std::hash<Key> n'est pas fourni par le programme ou l'utilisateur, il est désactivé.
• Sinon, std::hash<Key> est activé si toutes les conditions suivantes sont satisfaites :

• Toutes les exigences suivantes sont satisfaites :

• Hash (avec Key comme type d'argument de l'appel de fonction)
• DefaultConstructible
• CopyAssignable
• Swappable

• Étant donné les valeurs suivantes :

• h , un objet de type std::hash<Key> .
• k1 et k2 , des objets de type Key .

Toutes les exigences suivantes sont satisfaites :

• Si k1 == k2 est true , h ( k1 ) == h ( k2 ) est également true .
• Sauf si std::hash<Key> est une spécialisation définie par le programme , h ( k1 ) ne lèvera jamais d'exception.

• Sinon, std::hash<Key> est désactivé.

Les spécialisations désactivées ne satisfont pas Hash , ne satisfont pas FunctionObject , et les valeurs suivantes sont toutes 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

En d'autres termes, ils existent, mais ne peuvent pas être utilisés.

Fonctions membres

Spécialisations de la bibliothèque standard

Chaque en-tête qui déclare le template std::hash fournit également des spécialisations activées de std::hash pour les types suivants :

• tous les types arithmétiques sans qualificatifs cv
• tous les types énumération sans qualificatifs cv
• tous les types pointeur sans qualificatifs cv
• std::nullptr_t

En plus de cela, certains en-têtes fournissent également d'autres spécialisations activées std::hash pour les types de bibliothèque (voir ci-dessous ).

Spécialisations pour les types de bibliothèque

Notes

Les fonctions de hachage réelles dépendent de l'implémentation et ne sont pas tenues de satisfaire à d'autres critères de qualité que ceux spécifiés ci-dessus. Notamment, certaines implémentations utilisent des fonctions de hachage triviales (identité) qui mappent un entier sur lui-même. En d'autres termes, ces fonctions de hachage sont conçues pour fonctionner avec des conteneurs associatifs non ordonnés, mais pas comme des hachages cryptographiques, par exemple.

Les fonctions de hachage sont seulement tenues de produire le même résultat pour la même entrée lors d'une seule exécution d'un programme ; cela permet des hachages salés qui préviennent les attaques par déni de service par collision.

Il n'y a pas de spécialisation pour les chaînes de caractères C. std :: hash < const char * > produit un hash de la valeur du pointeur (l'adresse mémoire), il n'examine pas le contenu d'aucun tableau de caractères.

Des spécialisations supplémentaires pour std::pair et les types de conteneurs standards, ainsi que des fonctions utilitaires pour composer des hachages sont disponibles dans boost::hash .

Exemple

#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; // depuis C++20
};
// Avant C++20.
// bool operator==(const S& lhs, const S& rhs)
// {
//     return lhs.first_name == rhs.first_name && lhs.last_name == rhs.last_name;
// }
// La fonction de hachage personnalisée peut être un objet fonction autonome.
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); // ou utiliser boost::hash_combine
    }
};
// La spécialisation personnalisée de std::hash peut être injectée dans l'espace de noms 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); // ou utiliser 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"};
    // Utilisation de l'objet fonction autonome.
    std::cout << "hash(" << std::quoted(obj.first_name) << ", "
              << std::quoted(obj.last_name) << ") =\t"
              << MyHash{}(obj) << " (en utilisant MyHash) ou\n\t\t\t\t"
              << std::hash<S>{}(obj) << " (en utilisant la spécialisation injectée)\n";
    // Le hachage personnalisé permet d'utiliser des types personnalisés dans les conteneurs non ordonnés.
    // L'exemple utilisera la spécialisation injectée std::hash<S> ci-dessus,
    // pour utiliser MyHash à la place, passez-le comme second argument template.
    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';
}

hash("Rencontrez le nouveau patron...") =  10656026664466977650
hash("Hubert", "Farnsworth") =  12922914235676820612 (en utilisant MyHash) ou
                                12922914235676820612 (en utilisant la spécialisation injectée)
"Bender" "Rodriguez"
"Turanga" "Leela"
"Hubert" "Farnsworth"

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.