std::mbrtoc16(3)

🌸 std::mbrtoc16 — the C++ Standard Library one, bestie 💅

okay so picture this: you're deep in <cuchar> territory and you need to turn a narrow multibyte character into its UTF-16 glow-up. that's literally this function, and it's been serving since C++11. no cap. ✨

---

🎀 SYNOPSIS

defined in header <cuchar> — write it down, it's giving essential.

std::size_t mbrtoc16( char16_t* pc16,
                      const char* s,         (since C++11)
                      std::size_t n,
                      std::mbstate_t* ps );

it converts a narrow multibyte character to a UTF-16 character representation. that's the whole vibe check. 🦋

---

💖 DESCRIPTION (the main character section)

so if s is not a null pointer, the function inspects at most n bytes of the multibyte character string, starting with the byte that s points at, to figure out how many bytes it needs to complete the next multibyte character — shift sequences included, because of course they matter. 🙈

if the function decides the next multibyte character in s is complete and valid, it converts it to the corresponding 16-bit character and stores it in *pc16 (only if pc16 isn't null, obviously).

if the multibyte character in *s corresponds to a multi-char16_t sequence (think: a surrogate pair in UTF-16, the classic), then after the first call to this function, *ps gets updated in such a way that the next call to mbrtoc16 will write out the additional char16_t — without considering *s. like it remembers. it's got main character memory. 🧠✨

if s is a null pointer, then the values of n and pc16 are just ignored and the call is equivalent to:

std::mbrtoc16(nullptr, "", 1, ps)

if the wide character produced is the null character, the conversion state *ps represents the initial shift state. iconic reset behavior. 🔄

and the multibyte encoding this function uses? specified by the currently active C locale. so like, know your locale, bestie. 🌍

---

⭐ PARAMETERS ✨

• pc16 — pointer to the location where the resulting 16-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 (a hard cap, respect it 💀)
• ps — pointer to the conversion state object used when interpreting the multibyte string

---

🔥 RETURN VALUE

the first of the following that applies — read carefully, this list is doing the most:

• 0 if the character converted from s (and stored in *pc16 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 char16_t from a multi-char16_t character (e.g. a surrogate pair) has now been written to *pc16. no bytes are processed from the input in this case — zero, none, not a single one.
• -2 if the next n bytes constitute an incomplete, but so far valid, multibyte character. nothing is written to *pc16.
• -1 if an encoding error occurs. nothing is written to *pc16, the value EILSEQ is stored in errno, and the value of *ps is unspecified — so like, don't go trusting it, okay? 😭

---

🌈 EXAMPLE

// Run this code

#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
    char16_t c16;
    const char *ptr = &str[0], *end = &str[0] + str.size();

    while (std::size_t rc = std::mbrtoc16(&c16, ptr, end - ptr + 1, &state))
    {
        std::cout << "Next UTF-16 char: " << std::hex
                  << static_cast<int>(c16) << " obtained from ";
        if (rc == (std::size_t)-3)
            std::cout << "earlier surrogate pair\n";
        else if (rc == (std::size_t) - 2)
            break;
        else if (rc == (std::size_t) - 1)
            break;
        else
        {
            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-16 char: 0x7a obtained from 1 bytes [ 0x7a ]
Next UTF-16 char: 0xdf obtained from 2 bytes [ 0xc3 0x9f ]
Next UTF-16 char: 0x6c34 obtained from 3 bytes [ 0xe6 0xb0 0xb4 ]
Next UTF-16 char: 0xd83c obtained from 4 bytes [ 0xf0 0x9f 0x8d 0x8c ]
Next UTF-16 char: 0xdf4c obtained from earlier surrogate pair

see that last line? "earlier surrogate pair" — that's the -3 path eating, and honestly it ate. 👑

---

🦋 SEE ALSO

• c16rtomb — convert a 16-bit wide character to narrow multibyte string (C++11) (function) — the reverse glow-up, we love a symmetric icon.
• 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 mbrtoc16 — the OG, the blueprint, the source material 💜

---

aaaand that's the page, bestie! this one's from cppreference.com, dated 2024.06.10 — go drink some water and go convert some multibyte characters, you absolute legend 🫶💖✨