std::mbrtoc8(3)

✨ NAME ✨

std::mbrtoc8 — std::mbrtoc8. That’s literally the name, bestie 💅. This is the std::mbrtoc8(3) page from the C++ Standard Library, and it’s here to help you convert a narrow multibyte character into UTF-8. Slay.

---

🌸 Synopsis 🌸

          Defined in header <cuchar>
          std::size_t mbrtoc8( char8_t* pc8,

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

                               std::mbstate_t* ps );

Converts a narrow multibyte character to UTF-8 encoding. 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 UTF-8 and stores the first UTF-8 code unit in *pc8 (if pc8 is not null). No cap. ✨

If the UTF-8 encoding of the multibyte character in *s consists of more than one UTF-8 code unit, then after the first call to this function, *ps is updated in such a way that the next call to mbrtoc8 will write out the additional UTF-8 code units, without considering *s. It’s giving “I remember where we were, don’t worry.” 🫶

If s is a null pointer, the values of n and pc8 are ignored and the call is equivalent to std::mbrtoc8(nullptr, "", 1, ps). Iconic shortcut behavior. 💖

If the UTF-8 code unit produced is u8'\0', the conversion state *ps represents the initial shift state. Reset era. 🎀

The multibyte encoding used by this function is specified by the currently active C locale. So yeah, locale girlies, this one’s for you. 🌈

---

🫶 Parameters 🫶

• pc8 — pointer to the location where the resulting UTF-8 code units 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 *pc8 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>(-3) if the next UTF-8 code unit from a character whose encoding consists of multiple code units has now been written to *pc8. No bytes are processed from the input in this case. 😭
• static_cast<std::size_t>(-2) if the next n bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to *pc8. 🙈
• static_cast<std::size_t>(-1) if encoding error occurs. Nothing is written to *pc8, the value EILSEQ is stored in errno and the value of *ps is unspecified. 💀

---

🧚 Example 🧚

This section is incomplete Reason: no example

Not me showing up with no example 😭. It’s fine. We move. 🦋

---

👀 See also 👀

• c8rtomb — converts UTF-8 string to narrow multibyte encoding (C++20) (function). 🔥
• C documentation for mbrtoc8. 📚

---

🎀 Category 🎀

• Todo no example 🙈

---

mwah — that’s the whole vibe, sourced from http://cppreference.com, dated 2024.06.10, and it’s the std::mbrtoc8(3) page. 💜🎀✨