SDL_iconv_utf8_locale(3)

💖 SDL_iconv_utf8_locale(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_iconv_utf8_locale from <SDL3/SDL_stdinc.h>. it's a macro. it's tiny. it's iconic. let's get into it 🦋

---

✨ NAME ✨

SDL_iconv_utf8_locale — convert a UTF-8 string to the current locale's character encoding. literally that's the whole job description, and she does it flawlessly 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_stdinc.h>

#define SDL_iconv_utf8_locale(S)    SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)

look at her. one line. no cap. 🎀

---

🫶 DESCRIPTION 🫶

so this is a helper macro, and the whole point of her existence is that she might be more clear than calling SDL_iconv_string directly. like, sometimes you just wanna say "utf8 → locale, go" and not spell out every argument, yk? iykyk.

but — and this is the part where we sit down and have a serious chat — she double-evaluates her parameter. so do not pass in an expression with side-effects here. fr fr. if your argument does something spicy when it runs, it's gonna do that spicy thing twice, and that's a you problem, not a macro problem 😭

⚠️ reminder: no side-effect expressions in S. she will evaluate it twice and she will not apologise.

---

🧚 MACRO PARAMETERS 🧚

• S — the string to convert. that's it, that's the whole parameter list, she's low maintenance 💜

---

👑 RETURN VALUE 👑

Returns a new string, converted to the new encoding. or NULL on error. so like, check her before you use her, bestie 🙈

---

🌈 THREAD SAFETY 🌈

It is safe to call this macro from any thread. yes queen, thread-safe, no drama, go off 💖

---

⭐ AVAILABILITY ⭐

This macro is available since SDL 3.2.0. so if you're on something older, sorry babe, she hasn't been born yet 🥺

---

and that's the whole page!! every flag, every parameter, every return value, every thread-safety note, all of it, preserved and slaying ✨

this has been brought to you by Simple Directmedia Layer — SDL 3.4.18 — and yeah, the page footer says SDL_iconv_utf8_locale(3) down there too, consider it signed off with a kiss 🎀

mwah 💜 go convert some strings, you've got this 🫶