std::mbrtoc32(3)

💅 std::mbrtoc32(3) 💅

okay so this page comes from the C++ Standard Libary manual (yes bestie, that spelling, love that for us) and it's all about std::mbrtoc32(3). no cap, we're getting into multibyte-to-UTF-32 conversion and it's lowkey iconic.

---

💖 NAME 💖

std::mbrtoc32 — literally std::mbrtoc32, bestie. that's the name. periodt.

---

🦋 Synopsis 🦋

Defined in header <cuchar>:

          std::size_t mbrtoc32( char32_t* pc32,

                                const char* s,         (since C++11)
                                std::size_t n,

                                std::mbstate_t* ps );

Converts a narrow multibyte character to its UTF-32 character representation. slay.

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 figure out 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 32-bit character and stores it in *pc32 (if pc32 is not null). cute.

If the multibyte character in *s corresponds to a multi-char32_t sequence (not possible with UTF-32), then after the first call to this function, *ps is updated in such a way that the next calls to mbrtoc32 will write out the additional char32_t, without considering *s. yes, the state object is doing main character energy.

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

If the wide character produced is the null character, the conversion state *ps represents the initial shift state.

The multibyte encoding used by this function is specified by the currently active C locale. iykyk.

---

🎀 Parameters 🎀

• pc32 — pointer to the location where the resulting 32-bit 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 object used when interpreting the multibyte string 🦋

---

🔥 Return value 🔥

the first of the following that applies, bestie:

• 0 — if the character converted from s (and stored in *pc32 if non-null) was the null character.
• the number of bytes [1...n] of the multibyte character successfully converted from s.
• -3 — if the next char32_t from a multi-char32_t character has now been written to *pc32. no bytes are processed from the input in this case.
• -2 — if the next n bytes constitute an incomplete, but so far valid, multibyte character. nothing is written to *pc32.
• -1 — if encoding error occurs. nothing is written to *pc32, the value EILSEQ is stored in errno and the value of *ps is unspecified. 😭

---

✨ Examples ✨

run this code, bestie:

       // Run this code

        #include <cassert>
        #include <clocale>
        #include <cstring>
        #include <cuchar>
        #include <cwchar>
        #include <iomanip>
        #include <iostream>

        int main()
        {
            std::setlocale(LC_ALL, "en_US.utf8");

            std::string str = "z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"

            std::cout << "Processing " << str.size() << " bytes: [ " <<
       std::showbase;
            for (unsigned char c : str)
                std::cout << std::hex << +c << ' ';
            std::cout << "]\n";

            std::mbstate_t state{}; // zero-initialized to initial state
            char32_t c32;
            const char* ptr = str.c_str(), *end = str.c_str() + str.size() + 1;

            while (std::size_t rc = std::mbrtoc32(&c32, ptr, end - ptr,
       &state))
            {
                std::cout << "Next UTF-32 char: " << std::hex
                          << static_cast<int>(c32) << " obtained from ";
                assert(rc != (std::size_t) - 3); // no surrogates in UTF-32
                if (rc == (std::size_t) - 1)
                    break;
                if (rc == (std::size_t) - 2)
                    break;
                std::cout << std::dec << rc << " bytes [ ";
                for (std::size_t n = 0; n < rc; ++n)
                    std::cout << std::hex << +static_cast<unsigned
       char>(ptr[n]) << ' ';
                std::cout << "]\n";
                ptr += rc;
            }
        }

Output:

        Processing 10 bytes: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d
       0x8c ]
        Next UTF-32 char: 0x7a obtained from 1 bytes [ 0x7a ]
        Next UTF-32 char: 0xdf obtained from 2 bytes [ 0xc3 0x9f ]
        Next UTF-32 char: 0x6c34 obtained from 3 bytes [ 0xe6 0xb0 0xb4 ]
        Next UTF-32 char: 0x1f34c obtained from 4 bytes [ 0xf0 0x9f 0x8d 0x8c ]

---

👀 See also 👀

• c32rtomb — convert a 32-bit wide character to narrow multibyte string (C++11) (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 mbrtoc32 🌈

---

🌷 source: http://cppreference.com · version/date: 2024.06.10 · page: std::mbrtoc32(3) — mwah, bye bestie 💖