al_ustr_set_chr(3alleg5)

💖 al_ustr_set_chr — Allegro 5 API 💖

okay bestie, gather round, because this one is genuinely so useful and also lowkey a little bit dramatic if you play it wrong. it's al_ustr_set_chr, and it lives in the Allegro 5 API (that's the 3alleg5 manual section, iykyk). it swaps out one single code point for another. one. single. code point. no cap. 🎀

---

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

size_t al_ustr_set_chr(ALLEGRO_USTR *us, int start_pos, int32_t c)

look at her. so small. so powerful. 💅

---

🌸 DESCRIPTION 🌸

okay so here's the vibe: al_ustr_set_chr replaces the code point that begins at byte offset start_pos with c. that's it. that's the whole job. and she does it slayfully. ✨

but there are RULES, bestie, and we respect them:

• start_pos cannot be less than 0. like, don't even try it. that's not a thing. 🙈
• if start_pos is past the end of us, then the space between the end of the string and start_pos gets padded with NUL ('\0') bytes. yes, really, she'll just fill the gap with NULs like it's no big deal. iconic honestly. 💀
• if start_pos is not the start of a valid code point, that is an error, and the string will be left unmodified. she simply refuses. no half-edits, no mess, the string stays exactly how it was. main character boundaries, periodt. 👑

and then the return value, which you need to actually read, ngl:

• on success → returns the number of bytes written, which is the offset to the following code point. so like, where the next character starts. 🫶
• on error → returns 0. sad. tragic. zero. 😭

⚠️ real talk: the NUL-padding thing means this function can make your string longer than you might expect. that's not a bug, that's just the behavior. respect it.

---

🔥 SEE ALSO 🔥

• al_ustr_replace_range(3alleg5) — when you want to swap out a whole range instead of one lil code point, this is your girl 🌈

---

🦋 a lil sign-off 🦋

that's the whole page, bestie — brought to you by the Allegro reference manual, page al_ustr_set_chr(3alleg5). go forth, replace code points responsibly, and remember: if it returns 0, that's not a mood, that's an error. 💜✨🧚