gd_strtok(3)

💖 gd_strtok — tokenise a string using the GetData parser 💖

okay bestie, welcome to gd_strtok(3) from the GETDATA collection, no cap. this is the little function that chops your string into lil token crumbs using the GetData parser's rules, and honestly? she's iconic. ✨

🌸 SYNOPSIS 🌸

#include <getdata.h>

char *gd_strtok(DIRFILE *dirfile, const char *string);

like... two args, one dream. 🫶

✨ DESCRIPTION ✨

so here's the tea 🍓: gd_strtok() parses a string into a series of tokens, following the rules of the Dirfile metadata syntax (peep dirfile-format(5) if you wanna know the lore).

The first time you call gd_strtok(), you should pass the string you wanna parse in string. The first token gets returned to you. Then — and this is the important part, bestie, don't forget — on subsequent calls to parse that same string, string should be NULL (yes, exactly like strtok(3), the OG). Every time you call it like that, you get the next token back. 🎀

Now for the plot twist: the way the Dirfile tokeniser behaves actually varies between Dirfile Standards Versions. The Standards Version in play is the current Version of the loaded DIRFILE dirfile. Use gd_dirfile_standards(3) to retrieve or change that value, k?

Changing the Standards Version of dirfile while you're mid-parse will affect the parsing of subsequent tokens — but it does not affect tokens that were already returned. Past tokens are past tokens, we don't revisit. 💅

Also: a copy of the string is cached in the dirfile object. Which means calling gd_strtok() with different dirfiles will parse different strings. Each dirfile is living her own main character era. 👑

💅 RETURN VALUE 💅

Upon successful completion, gd_strtok() returns a copy of the first token — if string is non-NULL — or else a subsequent token from the previously specified string, if string is NULL.

⭐ Every single non-NULL pointer returned by gd_strtok() points to a new buffer allocated on the heap. Every. Single. One.

By default, strdup(3) is what allocates those buffers, but you can swap in an alternate memory manager by calling gd_alloc_funcs(3) before calling this function. Choose your fighter. 🥊

And listen — the caller is responsible for deallocating all these buffers. That's you. That's your job now. Free your memory, bestie, it's self care. 🧚

If no more tokens are available, or if an error occurred, NULL is returned. And if an error happened, it'll also set the dirfile error to a non-zero error value. Possible error values are:

• GD_E_ALLOC — a memory allocation error occurred. sad girl hours. 😭
• GD_E_ARGUMENT — there was no string to parse (i.e. string was NULL, but no previous call specified a string to parse). like, girl, what were you even tokenising??
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. 🚩
• GD_E_FORMAT — a syntax error was found in the string. typo era, we've all been there. 💀

You can retrieve the dirfile error by calling gd_error(3). And if you want a descriptive error string for the last error you hit, that's a call to gd_error_string(3). ✨

🦋 HISTORY 🦋

The gd_strtok() function appeared in GetData-0.8.0. a debut, a moment, a cultural reset. 🌈

👑 SEE ALSO 👑

• gd_dirfile_standards(3)
• gd_open(3)
• dirfile-format(5)

and that's the whole vibe! this page is living in Version 0.10.0, dated 25 December 2016, and it's filed under gd_strtok(3) — mwah, periodt. 💖🌸💅