gd_sarrays(3)

💖 NAME 💖

okay bestie, so gd_sarrays, gd_msarrays — they pull up a whole list of SARRAY values from a Dirfile. that's the whole gig. slay. ✨

🦋 SYNOPSIS 🦋

#include <getdata.h>

const char ***gd_sarrays(DIRFILE *dirfile);

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

🌸 DESCRIPTION 🌸

so gd_sarrays() goes and queries a dirfile(5) database — the one you hand it as dirfile — and it builds you a read-only list of the values of all the top-level SARRAY fields defined in that database, after type conversion to the data type specified by return_type. and bestie, for the list of valid symbols you can use for return_type, go peek at the gd_get_sarray(3) manual page, iykyk 💅

gd_msarrays() is literally the same vibe, except instead of top-level fields it makes you a list of values of SARRAY subfields under the parent field parent. cute.

the dirfile argument has got to point to a valid DIRFILE object that was previously created by a call to gd_open(3). no shortcuts, no guessing, no making one up yourself 🙈

and here's the tea about the array you get back: it will be de-allocated by a call to gd_close(3), so do NOT de-allocate it yourself. also, do not assume the list is in any particular order — the one exception being that it's guaranteed to be in the same order as the list of SARRAY fields returned by gd_field_list_by_type(3) or gd_mfield_list_by_type(3). if you wanna know how many values are in the array, hit up gd_nfields_by_type(3) or gd_nmfields_by_type(3). 👑

⚠️ big warning, bestie: the caller may not modify any values in the array, nor the array itself. doing so may cause database corruption. that is not a vibe. 😭

also the pointer you get back is only guaranteed valid until one of these happens:

• the function is called again with the same arguments
• the dirfile's metadata is modified (by adding, modifying or deleting an entry)
• the array gets de-allocated by a call to gd_close(3) or gd_discard(3)

so like… don't get attached. 🫶

oh and if you want the corresponding list of names for these fields, you can get that by calling gd_field_list_by_type(3) or gd_mfield_list_by_type(3). matching set fr fr. ✨

🎀 RETURN VALUE 🎀

when it works? gd_sarrays() and gd_msarrays(3) return a pointer to an array of arrays of strings. and for convenience, both levels of the array are terminated by NULL pointers. so thoughtful of it.

if there are literally no SARRAYs defined in the database, you get a pointer to a single-element array containing only the terminating NULL. that's it. that's the list. 💀

on error, gd_sarrays() returns NULL and stashes a negative-valued error code in the DIRFILE object, which you can retrieve with a subsequent call to gd_error(3). the possible error codes are:

• GD_E_ALLOC — the library couldn't allocate memory. it's giving broke. 😭
• GD_E_BAD_DIRFILE — the dirfile you supplied was invalid. not iconic of you.
• GD_E_INTERNAL_ERROR — an internal error happened in the library while it was trying to do the thing. this indicates a bug in the library. please report the incident to the GetData developers! 🐛

and if you want a descriptive error string for whatever went wrong, call gd_error_string(3). she'll tell you everything. 💅

🌈 HISTORY 🌈

gd_sarrays() first appeared in GetData-0.10.0. a legend was born. ⭐

🧚 SEE ALSO 🧚

• gd_entry_list(3)
• gd_error(3)
• gd_error_string(3)
• gd_get_sarray(3)
• gd_nentries(3)
• gd_open(3)
• dirfile(5)

okay that's the whole page bestie, go forth and read your SARRAYs responsibly 🫶 this was Version 0.10.0, dated 25 December 2016 — happy birthday to it, mwah 💖✨