std::mbrlen(3)

💅 std::mbrlen

okay so this page lives in the C++ Standard Library manual (section 3, bestie), and it's about one very specific little function. buckle up 🎀

✨ NAME ✨

std::mbrlen — yes the name is literally just std::mbrlen, that's the whole vibe, no notes 💀

✨ Synopsis ✨

so first things first, this bad boy is Defined in header <cwchar> 🫶

and here's the signature, exactly as written:

std::size_t mbrlen( const char* s, std::size_t n, std::mbstate_t* ps);

what does it do? it Determines the size, in bytes, of the remainder of the multibyte character whose first byte is pointed to by s, given the current conversion state ps. ✨

and here's the tea: this function is equivalent to the call std::mbrtowc(nullptr, s, n, ps ? ps : &internal) for some hidden object internal of type std::mbstate_t, except that the expression ps is evaluated only once. (yes, once. the compiler is not doing extra homework, and honestly? respect. 👑)

🌸 Parameters 🌸

• s — pointer to an element of a multibyte character string
• n — limit on the number of bytes in s that can be examined
• ps — pointer to the variable holding the conversion state

🔥 Return value 🔥

bestie, there are four possible moods this function can wake up in:

• 0 if the next n or fewer bytes complete the null character.
• the number of bytes (between 1 and n) that complete a valid multibyte character.
• (size_t) - 1 if encoding error occurs. 😭
• (size_t) - 2 if the next n bytes are part of a possibly valid multibyte character, which is still incomplete after examining all n bytes. (it's giving "to be continued..." energy 🦋)

🌈 Example 🌈

// Run this code

#include <clocale>
#include <cwchar>
#include <iostream>
#include <string>

int main()
{
    // allow mbrlen() to work with UTF-8 multibyte encoding
    std::setlocale(LC_ALL, "en_US.utf8");
    // UTF-8 narrow multibyte encoding
    std::string str = "水"; // or u8"\u6c34" or "\xe6\xb0\xb4"
    std::mbstate_t mb = std::mbstate_t();
    int len1 = std::mbrlen(&str[0], 1, &mb);
    if (len1 == -2)
        std::cout << "The first 1 byte of " << str
                  << " is an incomplete multibyte char (mbrlen returns -2)\n";
    int len2 = std::mbrlen(&str[1], str.size() - 1, &mb);
    std::cout << "The remaining " << str.size() - 1 << " bytes of " << str
                  << " hold " << len2 << " bytes of the multibyte character\n";
    std::cout << "Attempting to call mbrlen() in the middle of " << str
                  << " while in initial shift state returns "
                  << (int)mbrlen(&str[1], str.size(), &mb) << '\n';

}

✨ Output ✨

The first 1 byte of 水 is an incomplete multibyte char (mbrlen returns -2)
The remaining 2 bytes of 水 hold 2 bytes of the multibyte character
Attempting to call mbrlen() in the middle of 水 while in initial shift state returns -1

like, look at that output. it ate. 💅

🦋 See also 🦋

• mbrtowc — converts the next multibyte character to wide character, given state (function)
• mblen — returns the number of bytes in the next multibyte character (function)
• do_length — calculates the length of the ExternT string that would be consumed by conversion into given InternT buffer — [virtual] (virtual protected member function of std::codecvt<InternT,ExternT,StateT>)
• C documentation for mbrlen — the og crossover episode 🧚

okay that's the whole page, no cap, every single deet is in there 🌟 this one's brought to you by http://cppreference.com, version 2024.06.10, dated 2024.06.10 — mwah, go write some multibyte-safe code bestie, i'm obsessed with you 💖🎀✨