gd_fragment_namespace(3)

💖 gd_fragment_namespace — getdata manual, section 3 💖

okay bestie, pull up a chair 🫶 because today we're talking about gd_fragment_namespace(3), a little function from the getdata library, and honestly? it's giving "quietly powerful". it reports or changes the root namespace of a fragment in a dirfile database. yes. that's the whole vibe. let's get into it 💅

✨ NAME ✨

gd_fragment_namespace — report or change the root namespace of a fragment of a dirfile database 🎀

🌸 SYNOPSIS 🌸

#include <getdata.h>

const char *gd_fragment_namespace(DIRFILE *dirfile, int fragment_index,
       char *new_namespace);

🦋 DESCRIPTION 🦋

so, gd_fragment_namespace() does two jobs at once and it does them flawlessly: it can update and/or query the root namespace of a fragment inside the dirfile(5) database you hand it in dirfile. iconic behaviour, no cap ✨

here's the tea on how it decides what to do:

• if new_namespace is NULL, it just returns the current root namespace of the fragment indexed by fragment_index. simple. clean. we love her.
• if new_namespace is non-NULL, the root namespace gets changed first to the string you gave it, and then reported back to you. like, it does the thing and tells you about the thing. multitasking queen 👑
• the new namespace may optionally contain a single, trailing dot (.). just one. don't be greedy.
• wanna remove an existing root namespace? pass a pointer to the empty string ("") as new_namespace. boom, gone. periodt 💀

🚨 important, bestie: the root namespace of the root format file — that's the one indexed by fragment_index=0 — may not be changed. it is always the empty string. that's just the rules. don't fight it.

and dirfile must point to a valid DIRFILE object that was previously created by a call to gd_open(3). no random pointers, we're not doing chaos today 🙈

💅 RETURN VALUE 💅

on a good day (which is every day, when you use this function correctly), gd_fragment_namespace() returns a non-NULL pointer to a read-only string containing the current root namespace of the fragment you specified. yay 💖

• if new_namespace was non-NULL, that returned string is a copy of new_namespace.
• if the fragment's root namespace is empty, you get back a pointer to the empty string (""). still valid, still cute.

on error, this function returns NULL and sets the dirfile error to a non-zero error value. here's the full lineup of possible dirfile error values, and yes, we're listing every single one because we don't skip:

• GD_E_ACCMODE — the dirfile was opened read-only. can't write, won't write 💀
• GD_E_ALLOC — a memory allocation error occurred. tragic.
• GD_E_BAD_CODE — the supplied new_fragment was not a valid namespace. (yes, that's what it says. we report, we don't editorialise.)
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. not a real dirfile, sorry bestie.
• GD_E_BAD_INDEX — the supplied index was out of range. this error will also be returned if you attempt to change the root namespace of the root format file (fragment_index zero). we told you. 👀
• GD_E_DUPLICATE — attempting to change the root namespace resulted in a duplicated field definition. oops.
• GD_E_PROTECTED — the protection level of the specified fragment prohibits metadata changes. she's protected. respect the boundary 🔒

you can grab the dirfile error by calling gd_error(3), and if you want a descriptive error string for the last error encountered, hit up gd_error_string(3). they've got you 🫶

⭐ HISTORY ⭐

gd_fragment_namespace() appeared in GetData-0.10.0. a legend was born 🌈

🎀 SEE ALSO 🎀

• gd_alter_affixes(3)
• gd_include_ns(3)
• gd_open(3)
• dirfile(5)
• dirfile-format(5)

okay that's the whole page, you ate that reading session fr fr 🔥 this was Version 0.10.0, dated 25 December 2016, and it's gd_fragment_namespace(3) from the getdata manual — go forth and namespace responsibly, bestie 💜🧚