std::wcsncat(3)

💅 std::wcsncat

okay bestie, welcome to the std::wcsncat page from the C++ Standard Library — she's a little wide-string appender and honestly she ate 💖

---

✨ NAME ✨

std::wcsncat — yes that's literally it, the name is the name, we love a self-titled icon 👑

---

🌸 Synopsis 🌸

She lives in the header <cwchar>, as all the wide-char girlies do:

wchar_t* wcsncat( wchar_t* dest, const wchar_t* src, std::size_t count );

So here's the vibe check: she appends at most count wide characters from the wide string pointed to by src onto the end of the character string pointed to by dest — and she stops early if the null terminator gets copied. 🛑

The way that src[0] just replaces the null terminator sitting at the end of dest… main character energy, fr fr.

And the null terminator? Always appended at the end, no exceptions. So the maximum number of wide characters this function may write is count + 1. Math girlie. 🧮✨

⚠️ Lowkey important, ngl: the behavior is undefined if the destination array isn't large enough to hold the contents of both src and dest plus the terminating null wide character. Like, she will not check for you. She trusts you. Do not betray her. 😭

⚠️ Also undefined if the strings overlap. Just… don't. 🙈

---

🎀 Parameters 🎀

• dest — pointer to the null-terminated wide string you're appending to 🫶
• src — pointer to the null-terminated wide string you're copying from 🌈
• count — the maximum number of wide characters to copy, like a little limit, a lil snack portion 🍓

---

💜 Return value 💜

She gives you back dest. That's it. That's the return. Simple. Iconic. Periodt. 👑

---

🦋 Example 🦋

Run this code, bestie:

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

int main(void)
{
    wchar_t str[50] = L"Земля, прощай.";
    std::wcsncat(str, L" ", 1);
    std::wcsncat(str, L"В добрый путь.", 8); // only append the first 8 wide chars

    std::setlocale(LC_ALL, "en_US.utf8");
    std::wcout.imbue(std::locale("en_US.utf8"));
    std::wcout << str << '\n';
}

Possible output:

Земля, прощай. В добрый

See how she only grabbed the first 8 wide chars on that second call? Limited edition behavior, and we're obsessed. 💅✨

---

🔥 See also 🔥

• wcscat — appends a copy of one wide string to another (function)
• strncat — concatenates a certain amount of characters of two strings (function)
• wcscpy — copies one wide string to another (function)
• C documentation for wcsncat — the OG, the ancestor, the blueprint 👑

---

💖 okay that's the whole page, bestie! This gem came from http://cppreference.com, dated 2024.06.10, and it's the std::wcsncat(3) manual page — go forth and append responsibly, and remember: the array must be big enough or it's undefined behavior city 😭🫶✨