std::wcstombs(3)

🔥 std::wcstombs(3) — C++ Standard Library 🔥

Hiii bestie! Welcome to the C++ Standard Library manual, and specifically the page for std::wcstombs — that's std::wcstombs(3) if you're keeping score. This function is literally the one that takes your wide-character string and converts it into a narrow multibyte representation. It's giving main character energy in the wide-string-to-narrow-string world. Let me break it down for you. 💖✨

---

✨ NAME ✨

std::wcstombs — std::wcstombs. Yeah, the name is the same on both sides of the dash. That's just how it is, and honestly? Iconic. 💅

---

🦋 SYNOPSIS 🦋

Okay so first things first: this function is defined in the header <cstdlib>:

Defined in header <cstdlib>
std::size_t wcstombs( char* dst, const wchar_t* src, std::size_t len
       );

So here's the deal: it converts a sequence of wide characters from the array whose first element is pointed to by src to its narrow multibyte representation that begins in the initial shift state. The converted characters get stored in the successive elements of the char array pointed to by dst. And highkey important — no more than len bytes are written to the destination array. No cap. 📏

Each character is converted as if by a call to std::wctomb, except that the wctomb's conversion state is unaffected. That's the key detail, don't forget it. The conversion stops if:

• The null character was converted and stored. ✅
• A wchar_t was found that does not correspond to a valid character in the current C locale. 🚫
• The next multibyte character to be stored would exceed len. 🛑

---

💅 NOTES 💅

In most implementations, this function updates a global static object of type std::mbstate_t as it processes through the string, and cannot be called simultaneously by two threads. So like, thread safety? Lowkey not here, bestie. std::wcsrtombs should be used in such cases. Periodt. 🧵

POSIX specifies a common extension: if dst is a null pointer, this function returns the number of bytes that would be written to dst, if converted. Similar behavior is standard for std::wcsrtombs. So that's a thing, iykyk. 🔥

---

🌸 PARAMETERS 🌸

• dst — pointer to narrow character array where the multibyte character will be stored. 🎯
• src — pointer to the first element of a null-terminated wide string to convert. 📝
• len — number of byte available in the array pointed to by dst. (Yes, "byte" singular, that's literally what the page says, I'm not fixing it. 💀)

---

🎀 RETURN VALUE 🎀

On success, it returns the number of bytes (including any shift sequences, but excluding the terminating '\0') written to the character array whose first element is pointed to by dst. Slay. 💖

On conversion error (if invalid wide character was encountered), it returns static_cast<std::size_t>(-1). That's the sad path, bestie. 😭

---

👑 EXAMPLE 👑

Here's the code. Run it. Trust the process.

// Run this code

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

int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    // UTF-8 narrow multibyte encoding
    const wchar_t* wstr = L"z\u00df\u6c34\U0001d10b"; // or L"zß水𝄋"
    char mbstr[11];
    std::wcstombs(mbstr, wstr, 11);
    std::cout << "multibyte string: " << mbstr << '\n';
}

Output:

multibyte string: zß水𝄋

Look at that. The wide string L"zß水𝄋" (or L"z\u00df\u6c34\U0001d10b" if you're fancy with escapes) gets converted into a narrow multibyte string and prints exactly zß水𝄋. It ate and left no crumbs. Obsessed. 🤌💜

---

🦄 SEE ALSO 🦄

• wcsrtombs — converts a wide string to narrow multibyte character string, given state (function). This is the thread-safe one, iykyk.
• mbstowcs — converts a narrow multibyte character string to wide string (function). The reverse direction, also iconic.
• 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>). Get into it.
• C documentation for wcstombs. The C version, if you're curious.

---

And that's the tea, bestie! This page comes from http://cppreference.com, dated 2024.06.10, and it's the manual for std::wcstombs(3). Now go convert some wide strings and slay the day. 💜✨🎀