gd_put_string(3)

💖 gd_put_string(3) — GETDATA 💖

okay bestie, sit down, we're learning gd_put_string(3) today and honestly? it's giving simple but powerful. no cap.

✨ NAME ✨

gd_put_string — write a STRING or SARRAY element to a Dirfile database 🦋

🌸 SYNOPSIS 🌸

#include <getdata.h>

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

💅 DESCRIPTION 💅

so the way this works is: gd_put_string() goes and queries a dirfile(5) database — that's the one you named in dirfile — and then it takes the character string data_in and stores it in the STRING or SARRAY scalar field that you picked with field_code. very demure, very mindful.

and listen, tiny plot twist: if field_code points at a SARRAY field, your string gets stored as the first element. that's just how it is. 🎀

the dirfile argument? it must point to a valid DIRFILE object that you already made by calling gd_open(3). no shortcuts, no vibes-based dirfile objects, sorry babe. 😭

🚨 IMPORTANT, FR FR: because string values live in the dirfile metadata, the new value of field_code won't be written to disk until you flush the dirfile metadata with gd_metaflush(3), or until you close the dirfile with gd_close(3). so if you're out here wondering why your string ghosted the disk — that's why. periodt.

also, quick heads up: gd_put_sarray(3) gives you another way of storing STRING and SARRAY data to a Dirfile. options, we love to see it. 💖

⭐ RETURN VALUE ⭐

on success, gd_put_string() returns zero. slay. ✨

on error, it returns a negative-valued error code. and here's the whole roster of possible error codes, no gatekeeping:

• GD_E_ACCMODE — the dirfile you specified was opened read-only. can't write to something that said "no thank you." 🙈
• GD_E_BAD_CODE — the field you named in field_code wasn't found in the database. it's not there, bestie. 💀
• GD_E_BAD_DIRFILE — an invalid dirfile was supplied. 😭
• GD_E_BAD_FIELD_TYPE — the field_code you handed over referred to a field of some type other than SARRAY or STRING. wrong field, wrong vibe. 💅
• GD_E_INTERNAL_ERROR — an internal error happened in the library while it was trying to do the thing. this one means there's a bug in the library, and you should please report the incident to the maintainer. not your fault, queen. 🫶
• GD_E_PROTECTED — the fragment containing the string was protected from change. hands off. 🛑

and pssst — the error code also gets stored in the DIRFILE object itself, so you can go grab it after this function returns by calling gd_error(3). want a descriptive error string instead of a number? call gd_error_string(3). you're welcome. 🌈

🦋 HISTORY 🦋

okay story time, and it's a whole glow-up arc:

• the put_string() function appeared in GetData-0.4.0. back then it returned a size_t containing the length of the string written, or zero on error. different era, different energy.
• in GetData-0.7.0, this function was renamed to gd_put_strint().
• in GetData-0.10.0, this function's return value changed to zero on success, or else a negative-valued error code. main character evolution. 👑

🌈 SEE ALSO 🌈

dirfile(5), gd_close(3), gd_get_string(3), gd_error(3), gd_error_string(3), gd_metaflush(3), gd_open(3), gd_put_sarray(3).

go read them, they're iconic too. 💜

and that's the whole page, bestie!! this was Version 0.10.0, dated 25 December 2016, and honestly a little Christmas gift from the GetData girlies. mwah, bye!! 🎀💖✨🧚🍓