SDL_swprintf(3)

💖 SDL_swprintf(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_swprintf. she formats wide strings and she does NOT need a whole C runtime to do it. iconic behavior honestly. 🎀

---

✨ NAME ✨

SDL_swprintf — this works exactly like swprintf() but doesn't require access to a C runtime. no cap.

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_stdinc.h>

int SDL_swprintf(wchar_t *text, size_t maxlen, const wchar_t *fmt, ...);

---

🦋 DESCRIPTION 🦋

so what she does is format a wide string of up to maxlen-1 wchar_t values, converting each '%' item using the values you hand her through the variable arguments. cute, right?

now here's the part where she's lowkey better than some C runtimes: those runtimes be beefing over what to do with strings that are too big, but SDL_swprintf just null-terminates the output, treating that null-terminator as part of the maxlen count. but heads up bestie — if maxlen is zero, then no wide characters get written at all. none. zero. the void. 💀

she returns the number of _wide characters_ (not _codepoints_, bestie, those are different things) that should be written, not counting the null-terminator character. so if what she returns is a number >= maxlen, that means your output string got truncated. and if she returns a negative value? that's an error, she's going through it. 😭

⚠️ also pls pls pls: referencing the output string's pointer with a format item is undefined behavior. don't do it. not even a little. 🙈

---

🎀 FUNCTION PARAMETERS 🎀

• text — the buffer you're writing the wide string into. Must not be NULL. fr fr, not optional.
• maxlen — the maximum wchar_t values to write, including the null-terminator. yes, she counts it. she's thorough.
• fmt — a printf-style format string. Must not be NULL either. both of these gotta be real.
• ... — a list of values to be used with the format string. spill the tea, she'll format it. 💅

---

⭐ RETURN VALUE ⭐

Returns the number of wide characters that should be written, not counting the null-terminator char — or a negative value on error. that's it, that's the vibe check.

---

🧚 THREAD SAFETY 🧚

It is safe to call this function from any thread. yes queen, multithread away. 🫶

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. so if you're on something older, she's not there yet, sorry bestie. 👑

---

💡 reminder: text and fmt must not be NULL, maxlen of zero writes nothing at all, and touching the output pointer from inside a format item is undefined behavior. remember those three and you're golden. ✨

---

and that's the whole page, bestie!! this was brought to you by the Simple Directmedia Layer girlies, documenting SDL 3.4.18, and it's giving SDL_swprintf(3) energy all day long. go format something wide. slay. 💖🦋🌸