gd_add(3)

gd_add — bestie, we're adding a field to a Dirfile 💖

okay so this is gd_add(3) and gd_madd(3), two little icons from the GETDATA section of your manual, and they do exactly what the name says: they slide a brand new field into your Dirfile. no cap. 🎀

✨ SYNOPSIS ✨

#include <getdata.h>

int gd_add(DIRFILE *dirfile, const gd_entry_t *entry);

int gd_madd(DIRFILE *dirfile, const gd_entry_t *entry, const char *parent);

🌸 DESCRIPTION 🌸

So. gd_add() takes the field described by entry and adds it to the dirfile you passed in as dirfile. that's it, that's the job. 💅

gd_madd() is the same vibe but with a plot twist: it adds the field as a metafield under the field indicated by the field code parent. nesting era. 🪆

The whole form of entry is spelled out in excruciating (affectionate) detail on the gd_entry(3) man page — go read her. All relevant members of entry for the field type you specified must be properly initialised. like, all of them. no skipping.

• if entry specifies a CONST or CARRAY field, the field's data gets set to zero 🫥
• if entry specifies a STRING field, the field data gets set to the empty string 🫧

Now, the flags. the ONLY flags in the entry->flags member that get honoured are:

• GD_EN_HIDDEN — set it or clear it to control the hiddenness of the entry (peep gd_hidden(3) for the lore) 🙈
• GD_EN_COMPSCAL — tells us whether scalar parameters are initialised from the complex valued member or the purely real</c> member, since both are present for LINCOM, POLYNOM, and RECIP 💫

🦋 metafield tea 🦋

There are two ways to add a metafield and honestly pick whichever, they both eat:

1. call gd_madd() with entry->field containing only the metafield's name, or
2. call gd_add() with the fully formed "<parent-field>/<meta-field>" field code sitting in entry->field

Regardless of which interface you use: when you're adding a metafield, the value of entry->fragment_index is ignored, and GetData will add the new metafield to the same format specification fragment in which the parent field is defined. and if the parent field name you gave is an alias, the canonical name of the field gets substituted instead. canon event. 👑

🎀 literal params vs scalar params 🎀

Fields added with this interface may contain either literal parameters or parameters based on scalar fields.

• If an element of the entry->scalar array defined for the specified field type is non-NULL, that element gets used as the scalar field code, and the corresponding numerical member is ignored — and it does not need to be initialised. slay, less work for you.
• Conversely, if you want numerical parameters, set the corresponding entry->scalar elements to NULL. 🫶
• And if you're using an element of a CARRAY field, you also need to set entry->scalar_ind.

💀 RETURN VALUE 💀

On success, gd_add() and gd_madd() return zero. 🎉

On error, a negative-valued error code is returned. The possible error codes are:

• GD_E_ACCMODE — the specified dirfile was opened read-only. (bestie. you cannot write to a read-only dirfile. i know. 😭)
• GD_E_ALLOC — the library was unable to allocate memory.
• GD_E_BAD_CODE — the field name provided in entry->field contained invalid characters; or it or an input field did not contain the affected fragment's prefix or suffix. Alternately, the parent field code was not found, or was already a metafield.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid.
• GD_E_BAD_ENTRY — there was an error in the specification of the field described by entry, or the caller attempted to add a field of type RAW as a metafield. (RAW metafields are not it, apparently.)
• GD_E_BAD_INDEX — the entry->fragment_index parameter was out of range.
• GD_E_BAD_TYPE — the entry->data_type parameter provided with a RAW entry, or the entry->const_type parameter provided with a CONST or CARRAY entry, was invalid.
• GD_E_DUPLICATE — the field name provided in entry->field duplicated that of an already existing field. one of one, please.
• 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 GetData developers. 🐛
• GD_E_IO — an I/O error occurred while creating an empty binary file to be associated with a newly added RAW field.
• GD_E_PROTECTED — the metadata of the fragment was protected from change. Or, the creation of a RAW field was attempted and the data of the fragment was protected.
• GD_E_UNKNOWN_ENCODING — the encoding scheme of the indicated format specification fragment is not known to the library. As a result, the library was unable to create an empty binary file to be associated with a newly added RAW field.
• GD_E_UNSUPPORTED — the encoding scheme of the indicated format specification fragment does not support creating an empty binary file to be associated with a newly added RAW field.

✨ psst — the error code is also stored in the DIRFILE object, so you can grab it after this function returns by calling gd_error(3). and if you want a whole descriptive error string, hit up gd_error_string(3). 💖

📜 HISTORY 📜

• the functions dirfile_add() and dirfile_madd() appeared in GetData-0.4.0 — the original era.
• in GetData-0.7.0, they got renamed to gd_add() and gd_madd(). glow-up.
• in GetData-0.8.0, gd_add() first allowed adding metafields by providing the full (slashed) field name. this was the first version supporting fragment affixes, and in this version, gd_add() would apply the destination fragment's affixes to the supplied entry->field name. then in GetData-0.8.1 this changed: gd_add() now assumes entry->field contains the full field name, including any necessary affixes. character development.
• in GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. 🔄
• see gd_entry(3) for the history of the gd_entry_t structure. she has her own story.

👀 SEE ALSO 👀

gd_add_bit(3), gd_add_carray(3), gd_add_const(3), gd_add_divide(3), gd_add_lincom(3), gd_add_linterp(3), gd_add_multiply(3), gd_add_phase(3), gd_add_polynom(3), gd_add_raw(3), gd_add_recip(3), gd_add_sbit(3), gd_add_spec(3), gd_add_string(3), gd_entry(3), gd_error(3), gd_error_string(3), gd_madd_bit(3), gd_madd_carray(3), gd_madd_const(3), gd_madd_divide(3), gd_madd_lincom(3), gd_madd_linterp(3), gd_madd_multiply(3), gd_madd_phase(3), gd_madd_polynom(3), gd_madd_recip(3), gd_madd_sbit(3), gd_madd_spec(3), gd_madd_string(3), gd_metaflush(3), gd_open(3), dirfile-format(5)

and that's the whole page bestie, periodt 💅✨ this was Version 0.10.0, dated 25 December 2016 — go forth and add your fields, you absolute main character 🫶🎀🦋