set_ucodepage(3alleg4)

💖 set_ucodepage — the Allegro manual, but make it cute ✨

okay so bestie, we're in the Allegro game programming library manual, and today's episode is set_ucodepage from section 3. pull up a chair, grab a boba, this one's actually fun 🧋💅

✨ NAME ✨

set_ucodepage — sets the 8-bit to Unicode conversion tables. yeah. that's the whole vibe. it's the Allegro game programming library, and this is your girl for remapping codepages 🦋

🌸 SYNOPSIS 🌸

#include <allegro.h>

void set_ucodepage(const unsigned short *table, const unsigned short
*extras);

literally that's it. two pointers and a dream 🫶

👑 DESCRIPTION 👑

so here's the tea 🍓: when you pick the U_ASCII_CP encoding mode, Allegro leans on a whole set of tables to translate between 8-bit characters and their Unicode equivalents. and you, yes YOU, can call this function to hand it a custom set of mapping tables. which means — say it with me — you can support different 8-bit codepages. iconic. no cap. ✨

the table parameter points to an array of 256 shorts, and each one holds the Unicode value for the matching character in your codepage. 256 of them. all of them. don't skip any, bestie 💀

the extras parameter, if it's not NULL, points to a list of mapping pairs, and these get used when Allegro is reducing Unicode data down to your codepage. each pair is a Unicode value followed by the way it should be represented in your codepage. and the list? terminated by a zero Unicode value. that's the little "we're done here" signal 🎀

the whole point of extras is that it lets you build a many->one mapping — where a whole crowd of different Unicode characters all get represented by a single codepage value. the classic example being reducing accented vowels down to 7-bit ASCII. so é and è and ê can all just... become e. slay 🍓

now, the way Allegro actually uses these two:

• when Allegro needs to convert an ASCII string to a Unicode string, it only uses the table parameter.
• when Allegro converts a Unicode string to ASCII, it uses both parameters. first it loops through table looking for an index position pointing at the Unicode value it's trying to convert — meaning table is also used for reverse matching. if that fails, it falls back to the extras list. and if that fails too? Allegro just drops a ^ in there and gives up on the conversion entirely. 😭 that's the little shrug emoji of characters.

note bestie 📌 — Allegro ships with a default table and default extras already set internally. the default table will convert 8-bit characters to ^. and the default extras list reduces Latin-1 and Extended-A characters down to 7 bits in a sensible way — like, an accented vowel gets reduced to the same vowel without the accent. so if you don't call this function, you're not stranded. you're just living in the default house 🏠💜

🌈 SEE ALSO 🌈

• set_uformat(3alleg4)

and that's the whole page, bestie 💖 that was set_ucodepage(3alleg4) out of the Allegro manual, version 4.4.3. go forth and remap your codepages, you absolute main character 👑✨🦋