SDL_StepUTF8(3)

💖 SDL_StepUTF8 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we decode UTF-8 one codepoint at a time and it's honestly kind of a serve ✨

---

🌸 NAME 🌸

SDL_StepUTF8 — decode a UTF-8 string, one Unicode codepoint at a time. she's a little stepper, she takes it slow, she's mindful 🦋

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_stdinc.h>

Uint32 SDL_StepUTF8(const char **pstr, size_t *pslen);

---

💅 DESCRIPTION 💅

so here's the tea ☕: this function grabs the first Unicode codepoint out of the UTF-8 encoded string sitting in *pstr, and then — before it hands it back to you — it advances *pstr past all the bytes it just ate. like a lil cursor that scoots forward, no cap 🫶

it will not access more than *pslen bytes from the string. and *pslen gets adjusted too, subtracting however many bytes got consumed. so both your pointer and your length stay in sync, they're a matching set, iconic 💖

pslen is allowed to be NULL, and in that case the string _must_ be NULL-terminated, because the function will just blindly read until it sees the NULL char. bestie. she's trusting. do not betray her 😭

if *pslen is zero, it assumes the end of string is reached and returns a zero codepoint, regardless of what's actually in the string buffer. don't even worry about it.

if the resulting codepoint is zero (that's a NULL terminator, btw) or *pslen is zero, it will not advance *pstr or *pslen at all. zero movement. standing perfectly still. main character pause 💀

generally you call this function in a loop until it returns zero, adjusting its parameters each iteration. that's the whole vibe — step, step, step, done 🌈

now for the drama 🙈 if an invalid UTF-8 sequence shows up, this function returns SDL_INVALID_UNICODE_CODEPOINT and advances the string/length by one byte. which is to say: a multibyte sequence might produce several SDL_INVALID_UNICODE_CODEPOINT returns before it syncs back up to the next valid UTF-8 sequence. she's recalibrating. give her a sec ✨

several things can generate invalid UTF-8 sequences, including:

• overlong encodings
• the use of UTF-16 surrogate values
• truncated data

please refer to RFC3629 ⟨https://www.ietf.org/rfc/rfc3629.txt⟩ for details. iykyk 📚

---

🎀 FUNCTION PARAMETERS 🎀

• pstr — a pointer to a UTF-8 string pointer to be read and adjusted. yes that's a pointer to a pointer, she's layered, she has depth 💜
• pslen — a pointer to the number of bytes in the string, to be read and adjusted. NULL is allowed 🫶

---

👑 RETURN VALUE 👑

returns the first Unicode codepoint in the string. that's it, that's the gift 🎁

---

🧚 THREAD SAFETY 🧚

it is safe to call this function from any thread. go wild, take her everywhere, she's thread-safe 💅✨

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. so if you're on something older... bestie. upgrade 🍓

---

okay that's the whole page, mwah 😘 this one came to you courtesy of Simple Directmedia Layer, version SDL 3.4.18, and the page itself is SDL_StepUTF8(3). go decode something beautiful, you absolute legend 🦋💖🎀