SDL_iconv_string(3)

💖 SDL_iconv_string 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're talking about SDL_iconv_string(3) — the helper function that converts a string's encoding in ONE call. no drama, no multi-step ritual, just vibes ✨

---

🌸 NAME 🌸

SDL_iconv_string — helper function to convert a string's encoding in one call. that's it, that's the whole job, and she does it flawlessly 💅

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_stdinc.h>

char * SDL_iconv_string(const char *tocode,
                   const char *fromcode,
                   const char *inbuf,
                   size_t inbytesleft);

look at her. four params, one dream. 🦋

---

✨ DESCRIPTION ✨

This function converts a buffer or string between encodings in one pass. like, one and done, no cap 🫶

The string does not need to be NULL-terminated — not even a little. this function operates on the number of bytes specified in inbytesleft, whether there's a NULL character lurking somewhere in the buffer or not. so if you've got a NULL in the middle, she does not care, she is reading exactly inbytesleft bytes and that is that 😌

The returned string is owned by the caller, and should be passed to SDL_free when no longer needed. yes bestie, that means you are responsible for freeing it. don't just leave her hanging in memory forever, that's not the vibe 🙈

---

🔥 FUNCTION PARAMETERS 🔥

• tocode — the character encoding of the output string. examples are "UTF-8", "UCS-4", etc. this is where you're going 🛫
• fromcode — the character encoding of data in inbuf. this is where you're coming from 🛬
• inbuf — the string to convert to a different encoding.
• inbytesleft — the size of the input string _in bytes_. emphasis on BYTES, okay, not characters, not vibes, bytes 💀

---

👑 RETURN VALUE 👑

Returns a new string, converted to the new encoding, or NULL on error. so if you get NULL back, something went wrong and you should go check yourself before you wreck yourself 🌈

---

🧚 THREAD SAFETY 🧚

It is safe to call this function from any thread. multi-threaded besties, you are SO covered 💜

---

⭐ AVAILABILITY ⭐

This function is available since SDL 3.2.0. so if you're on anything older, sorry babe, she's not there yet 😭

---

🌈 SEE ALSO 🌈

• SDL_iconv_open(3)
• SDL_iconv_close(3)
• SDL_iconv(3)

---

and that's the whole page, bestie!! go forth and convert encodings responsibly 💖

this has been a Simple Directmedia Layer production, SDL 3.4.18 era, brought to you by the one and only SDL_iconv_string(3) — stan her, free your strings, and hydrate 🫶✨