al_cstr(3alleg5)

💖 al_cstr — the Allegro 5 API, bestie edition 💖

okay so this is al_cstr from the Allegro reference manual, and it lives in section 3alleg5 of the manual pages. it's short, it's sweet, it's lowkey iconic, and it has opinions about NUL terminators. let's get into it 🫶

---

✨ NAME ✨

al_cstr — Allegro 5 API

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

const char *al_cstr(const ALLEGRO_USTR *us)

---

🦋 DESCRIPTION 🦋

so the whole vibe here is: you hand it an ALLEGRO_USTR * and it gives you back a const char * pointer to the data inside that string. slay. but — and this is the part where you need to pay attention, bestie — that pointer is only valid while the ALLEGRO_USTR(3alleg5) object is not modified and not destroyed. it's giving "borrowed, not given". it is not yours. do not get attached. 💀

you can pass that pointer to functions that expect C-style strings, but there are caveats, and they are not optional reading:

• ALLEGRO_USTRs are allowed to contain embedded NUL ('\0') bytes. that means al_ustr_size(u) and strlen(al_cstr(u)) may not agree. like, they can genuinely just disagree with each other. not a bug, that's the design. 😭
• an ALLEGRO_USTR may be created in such a way that it is not NUL terminated. a string which is dynamically allocated will always be NUL terminated, but a string which references the middle of another string or region of memory will not be NUL terminated. so like… read the room before you strlen it. 🙈
• if the ALLEGRO_USTR references another string, the returned C string will point into the referenced string. and again — no NUL terminator will be added to the referenced string. it doesn't sneak one in. it doesn't help you out. it just points. periodt.

💀 real talk: the pointer is only valid while the object is unmodified and undestroyed. modify it or destroy it and your pointer is giving ghost. don't be out here using stale pointers, bestie, that's not main character energy, that's undefined behaviour energy.

---

🎀 SEE ALSO 🎀

• al_ustr_to_buffer(3alleg5)
• al_cstr_dup(3alleg5)

---

okay that's the whole page, you ate it, go forth and be normal about NUL terminators 💅✨

with love, the Allegro reference manual — al_cstr(3alleg5) 🦋💜