std::wcrtomb(3)

🌸 NAME 🌸

hey bestie, welcome to the std::wcrtomb(3) page from the C++ Standard Libary manual 💖 this one is literally called std::wcrtomb — that's the name, that's the vibe, periodt.

✨ Synopsis ✨

First things first: it's defined in header <cwchar> 🎀

std::size_t wcrtomb( char* s, wchar_t wc, std::mbstate_t* ps );

Okay so std::wcrtomb converts a wide character to its narrow multibyte representation. Main character energy for real.

If s is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of wc (including any shift sequences, and taking into account the current multibyte conversion state *ps), and stores the multibyte character representation in the character array whose first element is pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can be written by this function. No cap, that's the limit.

If s is a null pointer, the call is equivalent to std::wcrtomb(buf, L'\0', ps) for some internal buffer buf. Cute little internal-buffer moment 💅

If wc is the null wide character L'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state, and the conversion state parameter *ps is updated to represent the initial shift state. It's giving reset-to-default, iconic.

🎀 Parameters 🎀

• s — pointer to narrow character array where the multibyte character will be stored 🫶
• wc — the wide character to convert 🌟
• ps — pointer to the conversion state object used when interpreting the multibyte string 🌀

💅 Return value 💅

On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by s. Slay, it tells you how many bytes it used ✨

On failure (if wc is not a valid wide character), returns static_cast<std::size_t>(-1), stores EILSEQ in errno, and leaves *ps in unspecified state. That's the "it didn't work and *ps is not okay" path, so don't act surprised 😭

🌈 Example 🌈

The page says // Run this code, so bestie, run this code:

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

        void print_wide(const std::wstring& wstr)
        {
            std::mbstate_t state{};
            for (wchar_t wc : wstr)
            {
                std::string mb(MB_CUR_MAX, '\0');
                std::size_t ret = std::wcrtomb(&mb[0], wc, &state);
                std::cout << "multibyte char " << mb << " is " << ret << "
       bytes\n";
            }
        }

        int main()
        {
            std::setlocale(LC_ALL, "en_US.utf8");
            std::wstring wstr = L"z\u00df\u6c34\U0001f34c"; // or L"zß水🍌"
            print_wide(wstr);
        }

🍓 Output 🍓

multibyte char z is 1 bytes
multibyte char ß is 2 bytes
multibyte char 水 is 3 bytes
multibyte char 🍌 is 4 bytes

👑 See also 👑

• wctomb — converts a wide character to its multibyte representation (function) 🧚
• mbrtowc — converts the next multibyte character to wide character, given state (function) 🦋
• do_out — converts a string from InternT to ExternT, such as when writing to file — [virtual] (virtual protected member function of std::codecvt<InternT,ExternT,StateT>) 🔥
• C documentation for wcrtomb 📚

that's the whole page, bestie — source http://cppreference.com, date 2024.06.10, mwah 💋