gd_get_carray_slice(3)

💖 gd_get_carray_slice 💖

okay bestie, so this is a page from the GETDATA manual (that's the manual name, manifesting it early so you're not confused later 💅). These three functions — gd_get_carray, gd_get_carray_slice, and gd_get_constant — are your little trio for pulling CONST or CARRAY data out of a Dirfile database. no cap, they're so useful. let's go 🦋

✨ NAME ✨

gd_get_carray, gd_get_carray_slice, gd_get_constant — retrieve CONST or CARRAY data from a Dirfile database 🌸

🌈 SYNOPSIS 🌈

#include <getdata.h>

int gd_get_carray_slice(DIRFILE *dirfile, const char *field_code,
       unsigned int start, size_t len, gd_type_t return_type, void
       *data_out);

int gd_get_carray(DIRFILE *dirfile, const char *field_code, gd_type_t
       return_type, void *data_out);

int gd_get_constant(DIRFILE *dirfile, const char *field_code, gd_type_t
       return_type, void *data_out);

🎀 DESCRIPTION 🎀

okay so first up, gd_get_carray_slice() — this one goes and asks the dirfile(5) database you pass in as dirfile for the CONST or CARRAY scalar field_code 👑. and yes, that field_code can have a representation suffix, she's flexible like that 💅. then the data in the field gets converted to whatever data type return_type says, and it gets dropped into your own user-supplied buffer, data_out. the first element that gets stored is decided by start, and how many elements get stored is decided by len. periodt.

gd_get_carray() is basically the same vibe, except it hands you the entire field, as if you'd called gd_get_carray_slice() with start equal to zero and len equal to whatever gd_array_len(3) returns. iconic behaviour honestly.

and gd_get_constant()? she's exactly the same as calling gd_get_carray_slice() with start equal to zero and len equal to one. one and done, that's the energy 🎀

the dirfile argument has to point to a valid DIRFILE object that you made earlier with a call to gd_open(3) — no random garbage pointers bestie, i'm begging 😭. and data_out has to point to a valid memory location that's big enough to hold all the requested data of the return type you asked for. the number of elements that gd_get_carray() returns can be got by calling gd_array_len(3), iykyk.

unlike gd_getdata(3), calling gd_get_carray_slice() never results in a short read. if you try to read past the end of the field, you get an error, and literally no data comes back. so don't try it 🙈

the return_type argument should be one of these symbols, and it tells the function what type of data you want back:

• 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 💜
• GD_NULL — the null type: the database still gets queried like normal, but no data is returned. in this case data_out is ignored and it may be NULL. slay, free query ✨

the return type of the field does not have to match the type of the data stored in the database, bestie. type conversion gets performed as needed to give you the type you asked for. and here's the lil subtle bit 👀: if the field_code doesn't indicate a representation, but a conversion from a complex value to a purely real one is required, then only the real portion of the requested vector will be returned. just the real part. that's it. 💅

💀 RETURN VALUE 💀

on success, gd_get_carray(), gd_get_carray_slice(), and gd_get_constant() all return zero. on error, they return a negative-valued error code. here are the possible error codes, and listen, they're all important:

• 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. she's not there bestie 💀
• GD_E_BAD_DIRFILE — an invalid dirfile was supplied.
• GD_E_BAD_FIELD_TYPE — the supplied field_code was not a CONST nor CARRAY. wrong vibe entirely.
• GD_E_BAD_TYPE — an invalid return_type was specified.
• GD_E_BOUNDS — a request for data beyond the end of the field was made. you reached too far 🫶
• GD_E_INTERNAL_ERROR — an internal error occurred in the library while trying to perform the task. this indicates a bug in the library, so please report the incident to the maintainer. fr fr, tell them.

the error code also gets stored in the DIRFILE object, and you can retrieve it after the function returns by calling gd_error(3). and if you want a descriptive error string for whatever went wrong, call gd_error_string(3). so helpful 🌈

🦋 HISTORY 🦋

• the get_constant() function appeared in GetData-0.4.0. OG behaviour.
• in GetData-0.7.0, this function was renamed to gd_get_constant(). and in that same release, the gd_get_carray() and gd_get_carray_slice() functions also appeared. glow up ✨
• in GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code.

🌟 SEE ALSO 🌟

gd_array_len(3), gd_carrays(3), gd_error(3), gd_error_string(3), gd_open(3), gd_put_carray_slice(3), dirfile(5)

and that's the whole page bestie!! this was Version 0.10.0, dated 25 December 2016 — a lil christmas gift from the GetData girlies 🎁💖 go read your carrays, you've got this. mwah 💅✨