uconvert(3alleg4)

💖 uconvert — the glow-up your strings deserve 💖

okay bestie, so this one's from the Allegro manual, page uconvert(3alleg4), and it's literally the high-level string encoding conversion wrapper from the Allegro game programming library. she's the friendly face on top of the lowkey scary machinery. let's get into it 🫶

✨ NAME ✨

uconvert — high level string encoding conversion wrapper, Allegro game programming library. she converts. she's a wrapper. she's iconic. 💅

🌸 SYNOPSIS 🌸

#include <allegro.h>

char *uconvert(const char *s, int type, char *buf, int newtype, int size);

🦋 DESCRIPTION 🦋

okay so uconvert is the higher level function running on top of do_uconvert(). like, do_uconvert() is doing the actual heavy lifting backstage and uconvert is the one walking the red carpet 💅

what she does: converts the specified string s from type to newtype, storing at most size bytes into the output buf (including the terminating null character, don't forget the null bestie, she counts).

but here's the smart part — she checks before doing the conversion, and doesn't even bother if the string formats are already the same. and "already the same" means either:

• both types are equal, or
• one is ASCII, the other is UTF-8, and the string contains only 7-bit ASCII characters ✨

no wasted effort. she's efficient. we love that for her.

🎀 the NULL buf convenience (read the warning, fr fr)

as a convenience, if buf is NULL, she'll convert the string into an internal static buffer and the size parameter gets ignored entirely.

⚠️ okay so you should be wary of using this feature, though, because that buffer will be overwritten the next time this routine is called. do not expect the data to persist across any other library calls. the static buffer may hold less than 1024 characters, so you won't be able to convert large chunks of text. no cap, it's giving temporary. 😭

example time, look at her go:

char *p = uconvert(input_string, U_CURRENT, buffer, U_ASCII, 256);

🌈 RETURN VALUE 🌈

• returns a pointer to buf (or the static buffer if you used NULL) if a conversion was performed 🎉
• otherwise returns a copy of s

and in any case, bestie, you should use the return value rather than assuming that the string will always be moved to buf. like, don't assume, just read the return value. periodt. 👑

👑 SEE ALSO 👑

• set_uformat(3alleg4)
• need_uconvert(3alleg4)
• uconvert(3alleg4)
• uconvert_ascii(3alleg4)
• uconvert_toascii(3alleg4)
• do_uconvert(3alleg4)

(yes she references herself in SEE ALSO. main character energy only 💀✨)

mwah 💋 that's the page, courtesy of Allegro, version 4.4.3 — go convert something cute, and remember: use the return value, check for NULL, and never trust a static buffer to remember you. bye bestie 🦋💖