ustrtok(3)

✨ ustrtok ✨

ok so this is a page from the Allegro manual, section 3 (that's the library-functions girlies 💅), and today we're talking about ustrtok — she retrieves tokens from a string. Allegro game programming library, no big deal, just your fave retro game dev toolkit. 🎀

---

🌸 SYNOPSIS 🌸

#include <allegro.h>

char *ustrtok(char *s, const char *set);

that's it. that's the whole vibe. two args, one dream. ✨

---

💖 DESCRIPTION 💖

ok bestie listen up, because this one has lore.

This function retrieves tokens from s which are delimited by characters from set. 🦋 So like, set is the group of characters that count as separators, and s is the string you're chopping up.

To initiate the search, pass the string to be searched as s. For the remaining tokens, pass NULL instead. So the first call you hand her the actual string, and then every call after that you're like "keep going girl" and pass NULL. 🫶

⚠️ Warning: Since ustrtok alters the string it is parsing, you should always copy the string to a temporary buffer before parsing it. Also, this function is not re-entrant (ie. you cannot parse two strings at the same time).

fr fr, she's a main character — she does NOT share the spotlight. One string at a time, periodt. 😤

Example:

char *word;
char string[]="some-words with dashes";
char *temp = ustrdup(string);
word = ustrtok(temp, " -");
while (word) {
   allegro_message("Found `%s'\n", word);
   word = ustrtok(NULL, " -");
}
free(temp);

see how she ustrdup'd it first?? that's the copy-to-a-temp-buffer thing i literally just told you about. not me being right again. 💅 also notice " -" — space AND dash are both delimiters, iconic. and free(temp) at the end because we're responsible queens who clean up after ourselves. 🧚

---

👑 RETURN VALUE 👑

Returns a pointer to the token, or NULL if no more are found. 🌈

so when she hands you NULL, that's the signal that you're done, the tokens are all tokened, wrap it up. that's why the while (word) loop works — NULL is falsy, loop exits, slay. ✨

---

🌟 SEE ALSO 🌟

• uconvert(3)
• ustrchr(3)
• ustrrchr(3)
• ustrstr(3)
• ustrpbrk(3)
• ustrtok_r(3)
• allegro_message(3)
• ustrncpy(3)
• exgui(3)

(psst — ustrtok_r(3) is the re-entrant one if you need to parse two strings at once. iykyk 👀)

---

Allegro — version 4.4.3 — ustrtok(3)

k bye bestie, go tokenize something cute 💖🌸🦋✨🎀