std::collat...te::do_hash(3)

💅 std::collat...te::do_hash(3) — the group-chat cut

okay so real talk, bestie: this page is from the C++ Standard Library manual (the cppreference.com one, you know the vibe), and it's all about hashing strings the culturally aware way. sit down, grab a boba, we're learning 🍓

---

✨ NAME ✨

std::collate::hash, std::collate::do_hash — yes both of them, they're a package deal, no cap

---

🦋 Synopsis 🦋

Both of these live in the header <locale>, iconically:

Defined in header <locale>
public:                                                           (1)
long hash( const CharT* beg, const CharT* end ) const;
protected:                                                        (2)
virtual long do_hash( const CharT* beg, const CharT* end ) const;

1. the public member function 💖 — what it does is call the protected virtual member function do_hash of the most derived class. that's it, that's the whole job, she's a delegator and she's thriving
2. the protected virtual one 🎀 — it converts the character sequence [beg, end) into an integer value that is equal to the hash obtained for all strings that collate equivalent in this locale (like, compare() returns 0 for them, iykyk). and for two strings that do not collate equivalent? the probability that their hashes are equal should be very small, approaching 1.0 / std::numeric_limits<unsigned long>::max(). literally microscopic. not me doing probability math at 2am 😭

---

🌸 Parameters 🌸

• beg — pointer to the first character in the sequence to hash 👑
• end — one past the end pointer for the sequence to hash ✨

(yes bestie, "one past the end", that's the whole half-open range thing, it's giving classic C++)

---

💜 Return value 💜

the hash value that respects collation order. that's the tea. 🫖

---

🔥 Note 🔥

okay this part actually matters so listen up 🙈

the system-supplied locales normally do not collate two strings as equivalent (meaning compare() does not return 0) if basic_string::operator== returns false.

but — and this is the main character part — a user-installed std::collate facet may provide different collation rules. for example, it may treat strings as equivalent if they have the same Unicode normalized form. so like... your facet, your rules, your world 💅

---

🧚 Example 🧚

this one demonstrates a locale-aware unordered container, which is honestly so slay of it

#include <iostream>
#include <locale>
#include <string>
#include <unordered_set>

struct CollateHash
{
    template<typename CharT>
    long operator()(const std::basic_string<CharT>& s) const
    {
        return std::use_facet<std::collate<CharT>>(std::locale()).hash(
                   &s[0], &s[0] + s.size()
               );
    }
};
struct CollateEq
{
    template<typename CharT>
    bool operator()(const std::basic_string<CharT>& s1,
                    const std::basic_string<CharT>& s2) const
    {
        return std::use_facet<std::collate<CharT>>(std::locale()).compare(
                     &s1[0], &s1[0] + s1.size(),
                     &s2[0], &s2[0] + s2.size()
               ) == 0;
    }
};

int main()
{
    std::locale::global(std::locale("en_US.utf8"));
    std::wcout.imbue(std::locale());

    std::unordered_set<std::wstring, CollateHash, CollateEq> s2 = {L"Foo", L"Bar"};
    for (auto& str : s2)
        std::wcout << str << ' ';
    std::cout << '\n';
}

---

🌈 Possible output 🌈

Bar Foo

(emphasis on possible bestie, it's an unordered container, order is a vibe not a promise 💀)

---

⭐ See also ⭐

• std::hash<std::basic_string> — hash support for strings, (C++11) (class template specialization) 🔥

---

word of warning from your girl: the output really can come out in a different order, that's just unordered containers doing unordered-container things. no cap. 🙈

---

okay that's the whole page, you ate that 💅 stay hydrated, go compile something cute, and remember: cppreference.com, 2024.06.10 — that's where this page came from and when it was stamped. mwah 🎀🫶