gd_put_carray_slice(3)

💖 gd_put_carray_slice(3) — GETDATA 💖

okay bestie, so you know how we're out here living in a dirfile(5) database and you just want to write some data into a CARRAY or a CONST? yeah. that's this whole page. it lives in the GETDATA manual and it's literally the trio you need: gd_put_carray, gd_put_carray_slice, and gd_put_constant — all three write CONST or CARRAY data to a dirfile database. no cap. ✨

🦋 SYNOPSIS 🦋

#include <getdata.h>

int gd_put_carray_slice(DIRFILE *dirfile, const char *field_code,
       unsigned int start, size_t len, gd_type_t data_type, const void
       *data_in);

int gd_put_carray(DIRFILE *dirfile, const char *field_code, gd_type_t
       data_type, const void *data_in);

int gd_put_constant(DIRFILE *dirfile, const char *field_code, gd_type_t
       data_type, const void *data_in);

🌸 DESCRIPTION 🌸

So gd_put_carray_slice() writes data into a dirfile(5) database (the one you pass as dirfile), straight into the CARRAY scalar array named by field_code. the data gets converted from whatever type you say in data_type, and it's read from your user-supplied buffer data_in. where does it land? the first element it writes to is given by start, and the number of elements it stores is len. iconic. 💅

gd_put_carray() is the same vibe, except it writes the whole scalar array — exactly as if you'd called gd_put_carray_slice() with start equal to zero and len equal to whatever gd_array_len(3) hands back. and gd_put_constant()? that one is equivalent to calling gd_put_carray_slice() with start equal to zero and len equal to one. cute, tiny, one element. 🎀

🚨 none of these interfaces can write to field representations. nope. not happening. periodt.

The data_in argument must point to a valid memory location holding all the data you want written. and if you're curious how many elements gd_put_carray() is gonna store, call gd_array_len(3) and it'll tell you. now here's the thing — unlike gd_putdata(3), writing data past the end of the field is not permitted. sorry bestie, no overflow shenanigans. if you wanna add data to a CARRAY, first increase its length by calling gd_alter_carray(3), or another equivalent function. glow up the field before you fill it. 🌈

💜 data_type, the vibe check 💜

data_type should be one of these symbols, and it tells everyone what type the data pointed to by data_in actually is:

• GD_UINT8 — unsigned 8-bit integer
• GD_INT8 — signed (two's complement) 8-bit integer
• GD_UINT16 — unsigned 16-bit integer
• GD_INT16 — signed (two's complement) 16-bit integer
• GD_UINT32 — unsigned 32-bit integer
• GD_INT32 — signed (two's complement) 32-bit integer
• GD_UINT64 — unsigned 64-bit integer
• GD_INT64 — signed (two's complement) 64-bit integer
• GD_FLOAT32 — IEEE-754 standard 32-bit single precision floating point number
• GD_FLOAT64 — IEEE-754 standard 64-bit double precision floating point number
• GD_COMPLEX64 — C99-conformant 64-bit single precision complex number
• GD_COMPLEX128 — C99-conformant 128-bit double precision complex number

and here's the slay part: the type of the input data does not need to match the storage type of the field. type conversion will be performed as necessary to return the requested type. it just works. 🧚

the dirfile argument must point to a valid DIRFILE object that was previously created by a call to gd_open(3). don't be out here passing random garbage, okay? 🙈

✨ RETURN VALUE ✨

on success, gd_put_carray(), gd_put_carray_slice() and gd_put_constant() all return zero. on error, they return a negative-valued error code. possible error codes are:

• GD_E_ACCMODE — the specified dirfile was opened read-only. 😭
• GD_E_ALLOC — the library was unable to allocate memory.
• GD_E_BAD_CODE — the field specified by field_code was not found in the database.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid.
• GD_E_BAD_FIELD_TYPE — the supplied field_code was not a CONST nor a CARRAY.
• GD_E_BAD_TYPE — an invalid data_type was specified.
• GD_E_BOUNDS — a request for data beyond the end of the field was made.
• 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 maintainer. 🐛
• GD_E_PROTECTED — the fragment containing the constant was protected from change. 🔒

the error code is also stored in the DIRFILE object, and you can grab it after this function returns by calling gd_error(3). want a nice descriptive string for whatever went wrong? call gd_error_string(3). 🫶

👑 HISTORY 👑

• the put_constant() function appeared in GetData-0.4.0.
• in GetData-0.7.0, this function was renamed to gd_put_constant(). the functions gd_put_carray() and gd_put_carray_slice() functions also appeared in this release.
• in GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code.

💀 SEE ALSO 💀

dirfile(5), gd_array_len(3), gd_carrays(3), gd_error(3), gd_error_string(3), gd_get_carray_slice(3), gd_open(3), gd_put_constant(3)

and that's the whole page, bestie!! 🎀 this was Version 0.10.0, dated 25 December 2016 — yes, a literal Christmas gift from the GETDATA girlies. go write some CARRAY data. you got this. mwah. 💖✨