gd_strings(3)

💖 gd_strings — bestie edition 💖

okay so you're deep in the GETDATA docs, page gd_strings(3), and you need the ✨string values✨ out of a Dirfile. Say less. I got you. 🫶

🌸 NAME 🌸

gd_strings — pull a whole list of string values out of a Dirfile, no cap 💅

✨ SYNOPSIS ✨

#include <getdata.h>

const char **gd_strings(DIRFILE *dirfile);

const char **gd_mstrings(DIRFILE *dirfile, const char *parent);

🦋 DESCRIPTION 🦋

So gd_strings() goes into a dirfile(5) database — the one you point at with dirfile — and it puts together a read-only list of the values of all the STRING type fields defined in that database. Not the /META subfields tho, those are excluded, we don't do those here bestie. 🙈

Then there's gd_mstrings(), which is literally the same list but for STRING meta subfields of the parent field you hand it. Same energy, different layer. 👑

Oh and the dirfile argument? It has to point to a valid DIRFILE object, one that was already created by a call to gd_open(3). No random pointers, okay? That's not the vibe. 😭

🎀 RETURN VALUE 🎀

When it goes right, gd_strings() hands you back a pointer to an array of strings holding the values of all the STRING fields in the dirfile database. And gd_mstrings() does the same, returning a pointer to an array of strings with the values of all the STRING metafields under parent. 🍓

That returned array is terminated by a NULL pointer. And if the function doesn't hit an error, you're always getting a valid pointer back. If there's literally nothing to return? You still get a pointer — to an array that's just the NULL pointer and nothing else. Iconic minimalism. ✨

Heads up bestie: the array it returns gets de-allocated by a call to gd_close(3), and you should not de-allocate it yourself. Do not touch. 🚫

Also, do not assume the list is in any particular order — but it is guaranteed to be in the same order as the list of STRING fields returned by gd_field_list_by_type(3). And yeah, the array is terminated by a NULL pointer (saying it twice because it matters 💀). Want to know how many strings are in there? Get that from a call to gd_nfields_by_type(3). 🧮

And the caller may not modify any strings in the array, or the array itself. Doing that? Could cause database corruption. 😱 The pointer you get back is guaranteed valid until gd_strings() or gd_mstrings() is called again with the same arguments, or until the array is de-allocated by a call to gd_close(3) or gd_discard(3).

💀 when it goes wrong 💀

On error, these functions return NULL and stash a negative-valued error code in the DIRFILE object. You can grab that with a subsequent call to gd_error(3). Possible error codes, let's go:

• GD_E_ALLOC — the library couldn't allocate memory. It's giving out-of-ram energy. 😭
• GD_E_BAD_CODE — (gd_mstrings() only) the parent field code you supplied wasn't found, or it referred to a metafield itself. Rude.
• GD_E_BAD_DIRFILE — the dirfile you gave was invalid. Not valid, not slaying. 🙈

Want a descriptive error string for whatever went down? Call gd_error_string(3). 💖

🌈 HISTORY 🌈

• The get_strings() function showed up in GetData-0.3.0.
• The get_mstrings() function showed up in GetData-0.4.0.
• Then in GetData-0.7.0, these functions got renamed to gd_strings() and gd_mstrings(). Glow-up era. 👑

🫶 SEE ALSO 🫶

gd_error(3), gd_error_string(3), gd_field_list_by_type(3), gd_mstrings(3), gd_nfields_by_type(3), gd_open(3), gd_string(3), dirfile(5)

okay that's the whole page bestie, go get those strings 💅✨ This was Version 0.10.0, dated 25 December 2016 — merry christmas to the getdata girlies, periodt. 🎀🦋💜