gd_get_sarray_slice(3)

💖 gd_get_sarray_slice — GETDATA, section 3 💖

okay bestie, sit down, hydrate, because we're about to talk about pulling STRING and SARRAY data out of a dirfile database and honestly? it's giving library-core. 🎀

This is the gd_get_sarray_slice(3) page from the GETDATA manual. Two functions, one vibe: gd_get_sarray and gd_get_sarray_slice. They retrieve STRING or SARRAY data from a dirfile database. periodt. ✨

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_get_sarray_slice(DIRFILE *dirfile, const char *field_code,
       unsigned int start, size_t len, const char **data_out);

int gd_get_sarray(DIRFILE *dirfile, const char *field_code, const char
       **data_out);

like, yes, the second one wraps. she's long. she's worth it. 🫶

✨ DESCRIPTION ✨

so gd_get_sarray_slice() goes and queries a dirfile(5) database — the one you passed in as dirfile — for the STRING or SARRAY scalar field called field_code. what you get back are pointers to read-only string elements of that field, and they get stashed in the data_out buffer that you supply. heads up though: that buffer has to be big enough to hold len pointers. no cap. 💅

The first element that gets stored is decided by start, and how many elements get stored is decided by len.

gd_get_sarray() is basically the same girl but with main character energy — she returns the entire field, as if you'd called gd_get_sarray_slice() with start equal to zero and len equal to whatever gd_array_len(3) hands back.

The dirfile argument must point to a valid DIRFILE object that was previously created by a call to gd_open(3). (invalid dirfile? we don't know her. 🚫)

Wanna know how many elements gd_get_sarray() gave you? call gd_array_len(3). easy.

and here's the part that's lowkey iconic: unlike gd_getdata(3), calling gd_get_sarray_slice() never results in a short read. if you try to read past the end of the field you get an error, and no data will be returned. not a crumb. 😭

if field_code refers to a STRING field, it's treated as if it were a SARRAY field with only one element. cute, right? and if you want to see an example of how to swap your gd_get_string(3) calls for gd_get_sarray() calls, go read the gd_get_string(3) manual page. iykyk. 🦋

💀 RETURN VALUE 💀

On success, gd_get_sarray() and gd_get_sarray_slice() return zero. slay.

the storage for the strings these functions return is managed by GetData and should not be deallocated by the caller. do not free her. she is not yours. 🙈

On error, these functions return a negative-valued error code. possible error codes, bestie:

• GD_E_ALLOC — the library was unable to allocate memory. tragic.
• GD_E_BAD_CODE — the field specified by field_code was not found in the database. she's not here. 💀
• GD_E_BAD_DIRFILE — an invalid dirfile was supplied. we said valid. 🚫
• GD_E_BAD_FIELD_TYPE — the supplied field_code was not a STRING nor SARRAY. wrong vibe entirely.
• GD_E_BOUNDS — a request for data beyond the end of the field was made. you reached too far, babe. 😭
• GD_E_INTERNAL_ERROR — an internal error occurred in the library while trying to perform the task. This indicates a bug in the library. Please report the incident to the maintainer. (not me, not you — the maintainer. go tell them. 🫶)

also! the error code is stored in the DIRFILE object too, so you can grab it after the function returns by calling gd_error(3). and if you want a descriptive error string for the error, call gd_error_string(3). ✨

🎀 HISTORY 🎀

gd_get_sarray() and gd_get_sarray_slice() first appeared in GetData-0.10.0. glow up era. 👑

🦋 SEE ALSO 🦋

• gd_array_len(3)
• gd_get_string(3)
• gd_error(3)
• gd_error_string(3)
• gd_open(3)
• gd_put_sarray_slice(3)
• gd_sarrays(3)
• dirfile(5)

okay that's the whole page, you ate it, you understood it, go forth and read your arrays responsibly. 💖✨

this iconic little document is Version 0.10.0, dated 25 December 2016, and it lives in section 3 of the GETDATA manual. mwah. 💅🌸