al_ref_ustr(3alleg5)

✨ al_ref_ustr — the Allegro 5 API glow-up ✨

okay bestie, welcome to the <allegro5> corner of the Allegro 5 API (that's the 3alleg5 manual section, if you're keeping track 👑). this one is short but it's so useful, trust.

---

💖 NAME 💖

al_ref_ustr — Allegro 5 API. that's the whole name. she's concise, she's iconic, she does one thing and she does it well 🎀

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

const ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_INFO *info, const ALLEGRO_USTR *us,
   int start_pos, int end_pos)

look at that signature. four args. no cap, she's got range 💅

---

🦋 DESCRIPTION 🦋

so here's the tea: al_ref_ustr makes you a read-only string that just references the storage of another ALLEGRO_USTR(3alleg5) string. like, it's not copying anything, it's pointing at your friend's closet and saying "yeah that's mine now" 🫶

the info about the string — its size, for example — gets stored in the structure that the info parameter points to. that's info's whole job, she's holding the metadata 💜

and here's the part that makes her so lowkey elegant: the new string does not have any other storage allocated of its own. none. zero. so if you allocate that info structure on the stack, you literally do not need to do any explicit "free" operation. it's giving no cleanup, no stress ✨

the referenced interval is [start_pos, end_pos). both of those are byte offsets, not character offsets — pay attention, this matters, iykyk.

⚠️ the string is valid until the underlying string is modified or destroyed. so the moment your original string gets touched, your little reference string is gone, bestie. it's a borrowed fit, not a bought fit 😭

if you need a range of code-points instead of bytes, use al_ustr_offset(3alleg5) to find the byte offsets first. she'll translate for you 🧚

---

🌈 SEE ALSO 🌈

• al_ref_cstr(3alleg5)
• al_ref_buffer(3alleg5)

go read those too, they're the same vibe, different energy ⭐

---

and that's the whole page, babes 🍓 straight out of the Allegro reference manual, page al_ref_ustr(3alleg5). go forth and reference responsibly 💖✨