ici::doc::pod3::sdrtable(3)

📦 version 3.2.1, in ubuntu jammy

💖 ici::doc::pod3::sdrtable — ICI library functions 💖

okay bestie, sit DOWN, because we're about to talk about sdrtable, the Simple Data Recorder table management functions from the ICI library. this is your manual page, remixed, but every single fact is still here, no cap. 🫶

✨ NAME ✨

sdrtable — Simple Data Recorder table management functions 🌸

✨ SYNOPSIS ✨

#include "sdr.h"

Object  sdr_table_create        (Sdr sdr, int rowSize, int rowCount);
int     sdr_table_user_data_set (Sdr sdr, Object table, Address userData);
Address sdr_table_user_data     (Sdr sdr, Object table);
int     sdr_table_dimensions    (Sdr sdr, Object table, int *rowSize,
                                    int *rowCount);
int     sdr_table_stage         (Sdr sdr, Object table);
Address sdr_table_row           (Sdr sdr, Object table,
                                    unsigned int rowNbr);
int     sdr_table_destroy       (Sdr sdr, Object table);

✨ DESCRIPTION ✨

so the SDR table functions are the ones managing table objects inside the SDR. an SDR table is literally N rows of M bytes each, plus optionally one single word of user data (which is nominally the address of some other object living in the SDR's heap space). when you create a table you say how many rows and how long each row is, and those numbers stay locked in for the entire life of that table. periodt. 🔒

the table functions themselves only keep track of the table's structure and where it lives in the SDR, and they compute row addresses. that's it. reading and writing the actual row contents is a job for other SDR functions like sdr_read() and sdr_write(). and the format of the rows? entirely up to you, bestie. the table does not care. 💅

🎀 Object sdr_table_create(Sdr sdr, int rowSize, int rowCount)

creates a "self-delimited table" made of rowCount rows of rowSize bytes each, in the heap space of the SDR you point at. important vibe check: the content of the table, a two-dimensional array, is a single SDR heap space object of size (rowCount x rowSize). returns the address of the shiny new table on success, and zero on any error. 😭

🎀 void sdr_table_user_data_set(Sdr sdr, Object table, Address userData)

sets the "user data" word of table to userData. note that userData is nominally an Address but honestly it can be any value that occupies a single word. people usually use it to point at an SDR object that characterizes the table as a whole — like an SDR string holding a name. iconic use of one word tbh. ✨

🎀 Address sdr_table_user_data(Sdr sdr, Object table)

returns the value of the "user data" word of table, or zero on any error. that's the whole thing, she's simple and she serves. 💖

🎀 void sdr_table_dimensions(Sdr sdr, Object table, int *rowSize, int *rowCount)

reports back on the row size and row count of the table you asked about, exactly as they were specified when the table was created. no surprises, no glow-ups, just the original numbers. 📏

🎀 void sdr_table_stage(Sdr sdr, Object table)

stages table so that the array it encapsulates can actually be updated — go read the discussion of sdr_stage() in sdr(3) for the lore. the effect of this function is the same as:

sdr_stage(sdr, NULL, (Object) sdr_table_row(sdr, table, 0), 0)

🎀 Address sdr_table_row(Sdr sdr, Object table, unsigned int rowNbr)

returns the address of the rowNbrth row of table, so you can read or write the content of that row. returns -1 on any error. (and yes, -1 as an Address, we don't make the rules, we just document them 🫠)

🎀 void sdr_table_destroy(Sdr sdr, Object table)

destroys table, releasing all bytes of all rows and destroying the table structure itself. clean, thorough, no leftovers. ✨

🚨 BESTIE LISTEN. DO NOT use sdr_free() to destroy a table. doing that would leave the table's content allocated yet unreferenced, which is a memory leak and a whole tragedy. use sdr_table_destroy(). i am begging. 💀

✨ SEE ALSO ✨

go read those too, they're the supporting cast and they ate. 👑

and that's the page, babe 🦋 this was ici::doc::pod3::sdrtable(3) from the ICI library functions, and the footer energy is: perl v5.24.1, dated 2016-07-07. vintage but still slaying, fr fr. 💜🎀

📦 where this page comes from