std::strcoll(3)

💅 NAME 💅

okay so std::strcoll — this is from the C++ Standard Library (manpage std::strcoll(3)) — and it literally compares two null-terminated byte strings according to the current locale's collation rules 🌸. Basically, it's dictionary order but make it international, and it's giving main character energy for all your string-comparison needs 💅✨

---

✨ SYNOPSIS ✨

Defined in header <cstring>:

int strcoll( const char* lhs, const char* rhs );

It compares two null-terminated byte strings according to the current locale as defined by the LC_COLLATE category. That's literally the whole vibe 🫶

---

🎀 PARAMETERS 🎀

• lhs, rhs — pointers to the null-terminated byte strings you want to compare. Like, these are the two strings going head-to-head in the comparison arena 🥊💖

---

💖 RETURN VALUE 💖

• Negative value — if lhs is less than (precedes) rhs. So lhs comes first in the dictionary, periodt.
• 0 — if lhs is equal to rhs. They're literally the same, no cap.
• Positive value — if lhs is greater than (follows) rhs. So rhs comes first, and lhs is like "after you bestie" 💅

---

🦋 NOTES 🦋

okay so collation order is literally the dictionary order. Here's the tea ☕:

The position of the letter in the national alphabet (its equivalence class) has higher priority than its case or variant. So like, where the letter sits in the alphabet is more important than whether it's uppercase or lowercase, or which variant it is.

Within an equivalence class, lowercase characters collate before their uppercase equivalents — so a before A, b before B, etc. — and locale-specific order may apply to characters with diacritics. (You know, the cute accented ones like é, ö, ñ — those might have their own special order depending on the locale 🎀)

In some locales, groups of characters compare as single collation units. For example, "ch" in Czech follows "h" and precedes "i". And "dzs" in Hungarian follows "dz" and precedes "g". That's literally wild, right? Like, two or three letters are treated as one unit. Not me realizing that languages just have different vibes — and it's honestly so iconic — iykyk 🌈

---

🌈 EXAMPLE 🌈

// Run this code

#include <clocale>
#include <cstring>
#include <iostream>

int main()
{
    std::setlocale(LC_COLLATE, "cs_CZ.utf8");
    // Alternatively, ISO-8859-2 (a.k.a. Latin-2)
    // may also work on some OS:
    // std::setlocale(LC_COLLATE, "cs_CZ.iso88592");

    const char* s1 = "hrnec";
    const char* s2 = "chrt";

    std::cout << "In the Czech locale: ";
    if (std::strcoll(s1, s2) < 0)
        std::cout << s1 << " before " << s2 << '\n';
    else
        std::cout << s2 << " before " << s1 << '\n';

    std::cout << "In lexicographical comparison: ";
    if (std::strcmp(s1, s2) < 0)
        std::cout << s1 << " before " << s2 << '\n';
    else
        std::cout << s2 << " before " << s1 << '\n';
}

---

✨ OUTPUT ✨

In the Czech locale: hrnec before chrt
In lexicographical comparison: chrt before hrnec

okay so this is literally the "ch" rule from the notes in action 🔥 In Czech, "ch" follows "h", so hrnec comes before chrt in the Czech locale. But lexicographical comparison says chrt comes before hrnec because c comes before h in plain character order. The difference is lowkey iconic — and <highkey>it's exactly why strcoll exists</highkey> 💅✨

---

👑 SEE ALSO 👑

• wcscoll — compares two wide strings in accordance to the current locale (function) 💜
• do_compare — compares two strings using this facet's collation rules [virtual] (virtual protected member function of std::collate<CharT>) 🎀
• strxfrm — transform a string so that strcmp would produce the same result as strcoll (function) 🌟
• C documentation for strcoll

---

And that's the tea, bestie! 🍵 This page was brought to you by http://cppreference.com, version 2024.06.10, and it's literally std::strcoll(3) — now go out there and slay those string comparisons, no cap 💅✨🦋