funtablerowget(3)

💖 funtablerowget(3) — SAORD Documentation 💖

okay bestie, welcome to the funtablerowget(3) page, aka the one where we get Funtools rows. yes it's a section-3 manual page, yes it's from SAORD Documentation, and yes we are gonna make it make sense. no cap. 🦋

✨ NAME ✨

FunTableRowGet — get Funtools rows 🎀

✨ SYNOPSIS ✨

#include <funtools.h>

void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist,
                     int *nrow)

like, that's the whole vibe. one function, five args, zero drama (okay maybe a lil drama, keep reading). 💅

✨ DESCRIPTION ✨

so FunTableRowGet() literally retrieves rows from a Funtools binary table or raw event file, and it drops the values of the columns you picked with FunColumnSelect() into an array of user structs. and the way it just handles the glow-up for you?? the selected column values get automatically converted to the user data type you specified (and to native data format) whenever that's needed. obsessed. ✨

here's the arg-by-arg breakdown, bestie, don't skip:

• first argument — the Fun handle that's associated with this row data. it's giving "who am i even talking to" but it's a handle, so it knows.
• second argument, rows — the array of user structs where the selected columns are gonna be stored. and if you pass NULL?? the routine will automatically allocate space for this array itself. (and yes, that includes properly allocating the pointers inside each struct, if the "@" pointer type is used when selecting columns. 👑)

⚠️ okay important one: if you pass NULL in the second argument, you should free this space using the standard free() system call when you're done with the array of rows. like, don't just leave it there, bestie, that's a memory leak and it's not cute. 😭

• third argument, maxrow — the maximum number of rows to be returned. so if rows is allocated by the user, it should be at least of size maxrow*sizeof(evstruct).
• fourth argument, plist — a param list string. currently, the keyword/value pair "mask=transparent" is supported in the plist argument. if this string is passed in the call's plist argument, then all rows are passed back to the user (instead of just the rows passing the filter). 🫶

this is only useful when FunColumnSelect() is also used to specify "$region" as a column to return for each row. in that case:

• rows found within a region have a returned region value greater than 0 (corresponding to the region id of the region they're located in)
• rows passing the filter but not in a region have region value of -1
• rows not passing any filter have region value of 0

so, using "mask=transparent" and that returned region value, a program can process all rows and decide on an action based on whether a given row passed the filter or not. main character decision-making energy. 💅

• final argument — a pointer to an int variable that will return the actual number of rows returned. the routine returns a pointer to the array of stored rows, or NULL if there was an error. (and that pointer will be the same as the second argument, if the latter is non-NULL). 🌈

here's the example, verbatim, because we do not mess with code in this house:

/* get rows -- let routine allocate the row array */
while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
  /* process all rows */
  for(i=0; i<got; i++){
    /* point to the i'th row */
    ev = buf+i;
    /* rearrange some values. etc. */
    ev->energy = (ev->pi+ev->pha)/2.0;
    ev->pha = -ev->pha;
    ev->pi = -ev->pi;
  }
  /* write out this batch of rows */
  FunTableRowPut(fun2, buf, got, 0, NULL);
  /* free row data */
  if( buf ) free(buf);
}

see how it works? like, as shown above, successive calls to FunTableRowGet() will return the next set of rows from the input file until all rows have been read. i.e., the routine behaves like sequential Unix I/O calls such as fread(). it's giving "one at a time, patiently, like a good little loop". 😌

🌸 wanna see a fuller, more complete example? go peek at the evmerge example code. iykyk.

and one last thing, bestie — note that FunTableRowGet() also can be called as FunEventsGet(), for backward compatibility. yes, it has a whole other name. iconic of it, honestly. ✨

🌈 SEE ALSO 🌈

see funtools(7) for a list of Funtools help pages. go, read, slay. 📚💖

okay that's the whole page, you ate it up, periodt. 🎀 this masterpiece is from version 1.4.5, dated April 14, 2011, brought to you by SAORD Documentation — mwah, thanks for the lore, love u, bye bestie 💜🦋