gd_fragment_affixes(3)

💖 gd_fragment_affixes 💖

okay bestie, welcome to the gd_fragment_affixes(3) page — it lives in the GETDATA manual, and it's the one that tells you what affixes a fragment is wearing. let's get into it 🎀

✨ NAME ✨

gd_fragment_affixes — report the field affixes of a fragment of a Dirfile database 🦋

✨ SYNOPSIS ✨

#include <getdata.h>

int gd_fragment_affixes(DIRFILE *dirfile, int fragment_index, char
       **prefix, char **suffix);

✨ DESCRIPTION ✨

so basically, gd_fragment_affixes() goes and asks a dirfile(5) database — the one you point at with dirfile — for the field affixes of the fragment at index fragment_index. and like, what even are field affixes? they're the field prefix and field suffix, and they get tacked onto every field code chillin' in that fragment. it's giving accessory energy, fr fr 💅

the prefix and suffix parameters are pointers to memory locations where the addresses of the returned strings get stashed. and listen — the returned prefix does NOT contain the root namespace of the fragment. no cap. if you want that, you gotta go call gd_fragment_namespace(3) instead. iykyk.

also, the dirfile argument has to point to a valid DIRFILE object that was previously created by a call to gd_open(3). no bootleg dirfiles allowed 🙈

✨ RETURN VALUE ✨

when everything slays, gd_fragment_affixes() returns zero. 🫶

if they're non-empty, the prefix and suffix come back in heap-allocated buffers, and their addresses are returned in *prefix and *suffix. by default malloc(3) is the one doing the allocating, but you can bring a different allocator to the party by calling gd_alloc_funcs(3) before you call this function. and heads up bestie — the caller is responsible for deallocating the buffers. that's a you job, not a library job. if the fragment prefix or suffix is the empty string, NULL gets returned in the corresponding pointer. 💀

on error, a negative-valued error code comes back. in that case, the values of *prefix and *suffix are unspecified — but lowkey important: they will NOT be pointers to valid allocated memory. do not touch. do not free. do not pass go.

possible returned error codes, bestie:

• GD_E_ALLOC — a memory allocation error occurred. the malloc said no 😭
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid.
• GD_E_BAD_INDEX — the supplied index was out of range.

the error code also gets stored in the DIRFILE object, and you can grab it after this function returns by calling gd_error(3). want a descriptive error string instead? that's gd_error_string(3). iconic duo 🌈

✨ HISTORY ✨

• gd_fragment_affixes() appeared in GetData-0.8.0. a classic, honestly 👑
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code. glow-up behavior ⭐

✨ SEE ALSO ✨

• gd_alloc_funcs(3)
• gd_alter_affixes(3)
• gd_fragment_namespace(3)
• gd_include_affixes(3)
• gd_open(3)
• dirfile(5)
• dirfile-format(5)

and that's the whole vibe check 💜 this was Version 0.10.0, dated 25 December 2016 — go forth and read your affixes, bestie, you ate 🎀✨🦋