std::wcsncmp(3)

💖 std::wcsncmp 💖

okay bestie, welcome to std::wcsncmp(3) — that's the page for the C++ Standard Library function, and yes the NAME section literally just says std::wcsncmp back at you 😭 iconic of it honestly. It's the wide-string girlie of the strncmp family and she's got range. Let's get into it 🫶

✨ Synopsis ✨

First thing's first: this baby lives in the header <cwchar> 💅

int wcsncmp( const wchar_t* lhs, const wchar_t* rhs, std::size_t count );

🌸 Description 🌸

So what does she do? wcsncmp compares at most count wide characters of two null-terminated wide strings, and the comparison is done lexicographically — no cap, that's the whole vibe.

The sign of the result is the sign of the difference between the values of the first pair of wide characters that differ in the strings being compared. Like, she walks them side by side until somebody disagrees, and that disagreement's sign is what you get back 👑

⚠️ okay this is the serious part, listen up: the behavior is undefined if lhs or rhs are not pointers to null-terminated strings. Not a drill. Do not pass her a non-terminated string, she will not be okay 💀

🎀 Parameters 🎀

• lhs, rhs — pointers to the null-terminated wide strings to compare. the two besties facing off 🫶
• count — maximum number of characters to compare. how many steps of the walk we're doing before we call it 🌈

⭐ Return value ⭐

• Negative value if lhs appears before rhs in lexicographical order. she comes first, main character energy 🔥
• Zero if lhs and rhs compare equal. twin flames, matched perfectly ✨
• Positive value if lhs appears after rhs in lexicographical order. she's bringing up the rear, and that's fine too 💜

🦋 Example 🦋

the comment says // Run this code and honestly? run it. it's giving educational and cute at the same time 😭

#include <clocale>
#include <cwchar>
#include <iostream>
#include <locale>

void demo(const wchar_t* lhs, const wchar_t* rhs, int sz)
{
    int rc = std::wcsncmp(lhs, rhs, sz);
    if (rc == 0)
        std::wcout << "First " << sz << " characters of ["
                   << lhs << "] equal [" << rhs << "]\n";
    else if (rc < 0)
        std::wcout << "First " << sz << " characters of ["
                   << lhs << "] precede [" << rhs << "]\n";
    else if (rc > 0)
        std::wcout << "First " << sz << " characters of ["
                   << lhs << "] follow [" << rhs << "]\n";
}

int main()
{
    const wchar_t str1[] = L"안녕하세요";
    const wchar_t str2[] = L"안녕히 가십시오";

    std::setlocale(LC_ALL, "en_US.utf8");
    std::wcout.imbue(std::locale("en_US.utf8"));
    demo(str1, str2, 5);
    demo(str2, str1, 8);
    demo(str1, str2, 2);
}

💅 Output 💅

First 5 characters of [안녕하세요] precede [안녕히 가십시오]
First 8 characters of [안녕히 가십시오] follow [안녕하세요]
First 2 characters of [안녕하세요] equal [안녕히 가십시오]

look at that. three demos, three different vibes, all correct. we love a consistent icon 🎀

👑 See also 👑

• strncmp — compares a certain number of characters from two strings (function)
• wcscmp — compares two wide strings (function)
• wmemcmp — compares a certain amount of wide characters from two arrays (function)
• wcscoll — compares two wide strings in accordance to the current locale (function)
• C documentation for wcsncmp — the C-side of the family, still iconic in her own right

and that's the page, bestie! 🌟 this one came from http://cppreference.com, dated 2024.06.10, and it's std::wcsncmp(3) — go forth and compare your wide strings responsibly, and remember: null-terminate or it's undefined behavior, and we don't do undefined behavior in this group chat 💖✨🍓