set_ucodepage(3)

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

okay bestie, so this is set_ucodepage(3) from the Allegro manual (yes, that Allegro, the game programming library, we love her) and it's literally about teaching Allegro how to speak your 8-bit codepage. no cap. let's get into it 🦋

✨ NAME ✨

set_ucodepage</purgle> — sets the 8-bit to Unicode conversion tables. it's giving "Allegro game programming library", periodt. 💅

🌸 SYNOPSIS 🌸

#include <allegro.h>

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

look at her. two pointers, both unsigned short, both iconic. 👑

🎀 DESCRIPTION 🎀

so when you pick the U_ASCII_CP encoding mode, Allegro keeps a little set of tables around to convert between 8-bit characters and their Unicode equivalents. that's the whole vibe. and this function right here? it lets you swap in your own custom mapping tables, which means you can support alllll the different 8-bit codepages. main character energy fr fr. 💖

the table parameter points at an array of 256 shorts, and each one holds the Unicode value for a character in your codepage. one slot per character, no skipping, no gaps, 256 of them, okay bestie? 🫶

the extras parameter — and this is the important part — if it's not NULL, it points at a list of mapping pairs, which get used when Allegro is reducing Unicode data down to your codepage. every pair is a Unicode value followed by the way that value should be represented in your codepage. the list stops when it hits a zero Unicode value. so yeah, this is how you build a many→one mapping — like, a whole bunch of different Unicode characters can all get squished into a single codepage value. classic example: reducing accented vowels down to 7-bit ASCII. chef's kiss. 😌

now here's how Allegro actually uses these two things, because the order matters and it's lowkey the whole plot:

• Allegro uses the table parameter when it needs to convert an ASCII string to a Unicode string. 🐛
• But when Allegro converts a Unicode string to ASCII, it uses both parameters. first it loops through the table parameter looking for an index position that points at the Unicode value it's trying to convert (yes, so the table parameter is also used for reverse matching, keep up bestie 💅). if that fails, it moves on to the extras list. and if that fails too? Allegro just puts the character ^ in there and gives up on the conversion entirely. 💀

heads up, bestie: Allegro comes with a default table and extras set internally. the default table converts 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 cute, so thoughtful. 🌸

💜 SEE ALSO 💜

• set_uformat(3) — go read her next, she's part of the same friend group 🧚

okay that's the whole page!! this was set_ucodepage(3), straight from the Allegro manual, version 4.4.3. ty for coming to my ted talk, go convert some codepages, slay responsibly 💅✨🎀🦋