std::mbrtowc(3)

🦋 std::mbrtowc 🦋

okay bestie, welcome to the C++ Standard Libary manual page for std::mbrtowc — yes, manual page std::mbrtowc(3), keep the receipt. she converts narrow multibyte characters to wide characters and honestly? main character energy. 💅

---

✨ NAME ✨

std::mbrtowc — std::mbrtowc (that's the name, no notes 🎀).

---

🌸 Synopsis 🌸

Defined in header <cwchar>
std::size_t mbrtowc( wchar_t* pwc,
                     const char* s,
                     std::size_t n,
                     std::mbstate_t* ps );

okay so here's the tea: std::mbrtowc converts a narrow multibyte character to a wide character. periodt.

If s is not a null pointer, it inspects at most n bytes of the multibyte character string, beginning with the byte pointed to by s, to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences). If the function determines that the next multibyte character in s is complete and valid, it converts it to the corresponding wide character and stores it in *pwc (if pwc is not null).

If s is a null pointer, the values of n and pwc are ignored and call is equivalent to std::mbrtowc(nullptr, "", 1, ps).

If the wide character produced is the null character, the conversion state stored in *ps is the initial shift state. slay.

---

🎀 Parameters 🎀

• pwc — pointer to the location where the resulting wide character will be written
• s — pointer to the multibyte character string used as input
• n — limit on the number of bytes in s that can be examined
• ps — pointer to the conversion state used when interpreting the multibyte string

---

💖 Return value 💖

whichever of these hits first, bestie:

• 0 if the character converted from s (and stored in pwc if non-null) was the null character.
• the number of bytes [1...n] of the multibyte character successfully converted from s.
• static_cast<std::size_t>(-2) if the next n bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to *pwc.
• static_cast<std::size_t>(-1) if encoding error occurs. Nothing is written to *pwc, the value EILSEQ is stored in errno and the value of *ps is left unspecified.

that last one is the danger zone, okay? encoding error means no cute result and *ps is left unspecified — do not trust her after that. 💀

---

🧚 Example 🧚

// Run this code

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

void print_mb(const char* ptr)
{
    std::mbstate_t state = std::mbstate_t(); // initial state
    const char* end = ptr + std::strlen(ptr);
    int len;
    wchar_t wc;
    while ((len = std::mbrtowc(&wc, ptr, end-ptr, &state)) > 0)
    {
        std::wcout << "Next " << len << " bytes are the character " << wc << '\n';
        ptr += len;
    }
}

int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    // UTF-8 narrow multibyte encoding
    const char* str = "z\u00df\u6c34\U0001d10b"; // or u8"zß水𝄋"
                      // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";
    print_mb(str);
}

Output:

Next 1 bytes are the character z
Next 2 bytes are the character ß
Next 3 bytes are the character 水
Next 4 bytes are the character 𝄋

the way that output just eats every single time 🌈✨

---

🦋 See also 🦋

• mbtowc — converts the next multibyte character to wide character (function)
• wcrtomb — converts a wide character to its multibyte representation, given state (function)
• do_in — converts a string from ExternT to InternT, such as when reading from file; [virtual] (virtual protected member function of std::codecvt<InternT,ExternT,StateT>)
• C documentation for mbrtowc

---

that's the whole page, bestie. source/version/date check at the very end: http://cppreference.com, 2024.06.10, std::mbrtowc(3) — mwah 💋✨