uconvert(3)

💖 uconvert(3) 💖

okay bestie, welcome to the Allegro manual — this one's uconvert, the high level string encoding conversion wrapper from the Allegro game programming library. it's giving glow-up for your strings and we're gonna stan. 🦋

✨ SYNOPSIS ✨

#include <allegro.h>

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

🌸 DESCRIPTION 🌸

so basically uconvert is the higher level girlie that sits on top of do_uconvert(). she takes the string s and converts it from type to newtype, dropping at most size bytes into the output buf — and yes, that size count includes the terminating null character, she's thorough like that. 💅

but here's the iconic part: she does a little vibe check before doing the conversion, and if the string formats are already the same, she simply does not bother. and by "already the same" we mean 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, no cap. ✨

now, as a lil convenience, if buf is NULL she'll convert the string into an internal static buffer and the size parameter will just be ignored. lowkey handy but...

⚠️ be wary of using this feature, bestie!! that buffer gets overwritten the next time this routine is called, so do NOT expect the data to persist across any other library calls. and the static buffer may hold less than 1024 characters, so you won't be able to convert large chunks of text. she's a queen but she's not infinite. 😭

example time, look at her:

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

🫶 RETURN VALUE 🫶

if a conversion was performed, you get back a pointer to buf — or to the static buffer, if you passed NULL. otherwise? you get a copy of s. 💜

and in any case, please please please use the return value instead of assuming the string will always be moved to buf. don't do that to yourself. 🙈

👑 SEE ALSO 👑

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

and that's the whole page, bestie!! this was Allegro, version 4.4.3 — no date on this one, she's timeless like that 💅✨ mwah, go convert some strings, ily 🎀🦋💖