gd_put_sarray_slice(3)

💖 gd_put_sarray_slice(3) — the GETDATA girlies' guide 💖

okay so bestie, welcome to the GETDATA section 3 club, where we write STRING and SARRAY data into your dirfile and it's giving iconic 💅

✨ NAME ✨

gd_put_sarray, gd_put_sarray_slice — write STRING or SARRAY data to a Dirfile database 🦋

🌸 SYNOPSIS 🌸

#include <getdata.h>

int gd_put_sarray_slice(DIRFILE *dirfile, const char *field_code,
       unsigned int start, size_t len, const char **data_in);

int gd_put_sarray(DIRFILE *dirfile, const char *field_code, const char
       **data_in);

💜 DESCRIPTION 💜

so gd_put_sarray_slice() literally writes string data to a dirfile(5) database — the one you handed it as dirfile — straight into the STRING or SARRAY scalar array field_code. the spot where the first element of the field lands is start, and how many elements we're stashing is len. no cap ✨

and if field_code is pointing at a STRING field? we just treat it like it was a SARRAY field of length one. simple as that 🎀

gd_put_sarray() is the same vibe honestly, except it writes the whole scalar array, like you'd called gd_put_sarray_slice() with start equal to zero and len equal to whatever gd_array_len(3) gives back 👑

the data_in argument has to point to an array of pointers to character strings — those are the values we're storing. and if you wanna know how many elements gd_put_sarray() is gonna store, call gd_array_len(3) and it'll tell you 💫

🚨 okay important bestie: unlike gd_putdata(3), writing data past the end of the field is not permitted. not allowed. we do not do that here. 🙈

so if you wanna add data to a SARRAY, first make it longer by calling gd_alter_sarray(3), or some other equivalent function. grow first, then write. periodt 💅

oh and p.s. — gd_put_string(3) is another way to write data to a STRING field, if you want options 🫶

🔥 RETURN VALUE 🔥

on success, gd_put_sarray() and gd_put_sarray_slice() return zero. slay. 💖

on error, they return a negative-valued error code 😭 and the possible ones are:

• GD_E_ACCMODE — the dirfile you specified was opened read-only. can't write to a locked door, babe 💀
• GD_E_ALLOC — the library could not allocate memory. it's not you, it's the heap 😔
• GD_E_BAD_CODE — the field specified by field_code was not found in the database. ghosted fr fr 👻
• GD_E_BAD_DIRFILE — an invalid dirfile was supplied. not a real one bestie 🙈
• GD_E_BAD_FIELD_TYPE — the field_code you gave was not a STRING nor a SARRAY. wrong genre 💅
• GD_E_BOUNDS — a request for data beyond the end of the field was made. we talked about this 🚨
• GD_E_INTERNAL_ERROR — an internal error happened inside the library while it was trying to do the thing. this means there's a bug in the library, so please report the incident to the maintainer! 😭
• GD_E_PROTECTED — the fragment containing the constant was protected from change. hands off, it's guarded 🔒

the error code also gets stored in the DIRFILE object, and you can grab it after this function returns by calling gd_error(3) ✨ and if you want a descriptive error string for whatever went wrong, call gd_error_string(3) and it'll spill the tea 🍓

🦋 HISTORY 🦋

the gd_put_sarray() and gd_put_sarray_slice() functions appeared in GetData-0.10.0. they've been here, being iconic, since then 👑

🌈 SEE ALSO 🌈

dirfile(5), gd_array_len(3), gd_sarrays(3), gd_error(3), gd_error_string(3), gd_get_sarray_slice(3), gd_open(3), gd_put_string(3)

and that's the whole page, bestie 💜 this was Version 0.10.0, dated 25 December 2016, and it lives in the gd_put_sarray_slice(3) corner of the manual — go forth and write those strings, you absolute main character 🎀✨🫶