std::mbtowc(3)

🎀 NAME 🎀

okay bestie, welcome to the std::mbtowc(3) page from the C++ Standard Libary — she's giving multibyte-to-wide-character conversion ✨. std::mbtowc - std::mbtowc (yes, the name is literally the name, and honestly? iconic).

✨ SYNOPSIS ✨

Defined in header <cstdlib>:

int mbtowc( wchar_t* pwc, const char* s, std::size_t n );

So here's the vibe: it converts a multibyte character whose first byte is pointed to by s to a wide character, and that wide character is written to *pwc if pwc is not null. 🫶

If s is a null pointer, it resets the global conversion state and determines whether shift sequences are used. no cap, that's the whole synopsis.

🌸 PARAMETERS 🌸

• s — pointer to the multibyte character
• n — limit on the number of bytes in s that can be examined
• pwc — pointer to the wide character for output

💖 RETURN VALUE 💖

If s is not a null pointer, it returns the number of bytes that are contained in the multibyte character, or -1 if the first bytes pointed to by s do not form a valid multibyte character, or 0 if s is pointing at the null character '\0'.

If s is a null pointer, it resets its internal conversion state to represent the initial shift state and returns 0 if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).

🦋 NOTES 🦋

Bestie, pay attention here: each call to mbtowc updates the internal global conversion state (a static object of type std::mbstate_t, only known to this function). If the multibyte encoding uses shift states, care must be taken to avoid backtracking or multiple scans.

In any case, multiple threads should not call mbtowc without synchronization: std::mbrtowc may be used instead. this is the important caveat, fr fr.

🍓 EXAMPLE 🍓

       // Run this code

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

        int print_mb(const char* ptr)
        {
            std::mbtowc(nullptr, 0, 0); // reset the conversion state
            const char* end = ptr + std::strlen(ptr);
            int ret{};
            for (wchar_t wc; (ret = std::mbtowc(&wc, ptr, end - ptr)) > 0; ptr
       += ret)
                std::wcout << wc;
            std::wcout << '\n';
            return ret;
        }

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

🌈 OUTPUT 🌈

zß水𝄋

👑 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_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 mbtowc

kisses and sparkles, bestie 💅 — this page is from http://cppreference.com, version 2024.06.10, and it's literally std::mbtowc(3) 🎀✨