ici::doc::pod3::sdrlist(3)

📦 version 3.2.1, in ubuntu jammy

🎀 sdrlist — bestie edition 🎀

okay so this is a page from the ICI library functions manual (section 3, the library-call girlies 💅), and it's all about sdrlist, the Simple Data Recorder list management functions. yes the acronym is SDR. yes we love her. let's go ✨

✨ NAME ✨

sdrlist — Simple Data Recorder list management functions 🫶

🌸 SYNOPSIS 🌸

#include "sdr.h"

typedef int (*SdrListCompareFn)(Sdr sdr, Address eltData, void *argData);
typedef void (*SdrListDeleteFn)(Sdr sdr, Object elt, void *argument);

[see description for available functions]

like. the actual list of functions is down in the DESCRIPTION, bestie, keep scrolling 📜

💖 DESCRIPTION 💖

so these functions manage doubly-linked lists living in managed SDR heap space. there are two kinds of objects in play: lists and list elements.

  • a list knows how many elements it has, and what its start and end elements are 🌈
  • an element knows what list it belongs to, and who comes before and after it in that list
  • an element also knows its content, which is normally the SDR Address of some object in the SDR heap

a list may also be sorted, which speeds up searching for a particular element. iconic behaviour honestly 🔥

the functions, one by one 👑

  • Object sdr_list_create(Sdr sdr) — creates a brand new list object in the SDR; the new list starts out containing zero list elements. returns the address of the new list, or zero on any error. baby's first list 🎀
  • void sdr_list_destroy(Sdr sdr, Object list, SdrListDeleteFn fn, void *arg) — destroys a list, freeing all elements of list. if fn is non-NULL, that function gets called once for each freed element; when it's called, fn is handed the Address that is the element's data and the argument pointer that was passed to sdr_list_destroy().
⚠️ do not use sdr_free to destroy an SDR list, bestie. that would leave the elements of the list allocated yet unreferenced. we do not do that. 💀
  • int sdr_list_length(Sdr sdr, Object list) — returns the number of elements in the list, or -1 on any error.
  • void sdr_list_user_data_set(Sdr sdr, Object list, Address userData) — sets the "user data" word of list to userData. heads up: userData is nominally an Address but can literally be any value that fits in a single word. it's typically used to point to an SDR object that somehow characterizes the list as a whole, like a name. cute little metadata slot ✨
  • Address sdr_list_user_data(Sdr sdr, Object list) — returns the value of the "user data" word of list, or zero on any error.
  • Object sdr_list_insert(Sdr sdr, Object list, Address data, SdrListCompareFn fn, void *dataBuffer) — creates a new list element whose data value is data, and inserts that element into the list. if fn is NULL, the new element is just appended to the list. otherwise, the new element gets inserted after the last element in the list whose data value is "less than or equal to" the data value of the new element (that new value being in dataBuffer), according to the collating sequence established by fn. returns the address of the newly created element, or zero on any error.
  • Object sdr_list_insert_first(Sdr sdr, Object list, Address data)
  • Object sdr_list_insert_last(Sdr sdr, Object list, Address data) — creates a new element and inserts it at the front/end of the list. 🫶 this function should not be used to insert a new element into any ordered list — use sdr_list_insert() instead, fr fr. returns the address of the newly created list element on success, or zero on any error.
  • Object sdr_list_insert_before(Sdr sdr, Object elt, Address data)
  • Object sdr_list_insert_after(Sdr sdr, Object elt, Address data) — creates a new element and inserts it before/after the specified list element. same deal: this should not be used to insert into any ordered list — use sdr_list_insert() instead. returns the address of the newly created list element, or zero on any error.
  • void sdr_list_delete(Sdr sdr, Object elt, SdrListDeleteFn fn, void *arg) — delete elt from the list it's in. if fn is non-NULL, that function will be called upon deletion of elt; when it's called, it's passed the Address that is the list element's data value, plus the arg pointer that was passed to sdr_list_delete(). bye bestie 👋
  • Object sdr_list_first(Sdr sdr, Object list)
  • Object sdr_list_last(Sdr sdr, Object list) — returns the address of the first/last element of list, or zero on any error.
  • Object sdr_list_next(Sdr sdr, Object elt)
  • Object sdr_list_prev(Sdr sdr, Object elt) — returns the address of the element following/preceding elt in that element's list, or zero on any error.
  • Object sdr_list_search(Sdr sdr, Object elt, int reverse, SdrListCompareFn fn, void *dataBuffer); — searches a list for an element whose data matches the data in dataBuffer, starting at the indicated initial list element. if the compare function is non-NULL, the list is assumed to be sorted in the order implied by that function, and the function is automatically called once for each element of the list until it returns a value that is greater than or equal to zero (where zero indicates an exact match, and a value greater than zero indicates that the list contains no matching element). each time compare is called it is passed the Address that is the element's data value and the dataBuffer value passed to sm_list_search(). if reverse is non-zero, then the list is searched in reverse order (starting at the indicated initial list element) and the search ends when compare returns a value that is less than or equal to zero. if compare is NULL, then the entire list is searched (in either forward or reverse order, as directed) until an element is located whose data value is equal to ((Address) dataBuffer). returns the address of the matching element if one is found, 0 otherwise. detective mode 🔍
  • Object sdr_list_list(Sdr sdr, Object elt) — returns the address of the list to which elt belongs, or 0 on any error.
  • Address sdr_list_data(Sdr sdr, Object elt) — returns the Address that is the data value of elt, or 0 on any error.
  • Address sdr_list_data_set(Sdr sdr, Object elt, Address data) — sets the data value for elt to data, replacing the original value. returns the original data value for elt, or 0 on any error. the original data value for elt may or may not have been the address of an object in heap data space; and even if it was, that object was NOT deleted. no sneaky cleanup, okay? 🙈
🚨 Warning: changing the data value of an element of an ordered list may ruin the ordering of the list. you have been warned, bestie.

💅 USAGE 💅

when inserting elements or searching a list, you may optionally provide a compare function shaped like this:

int user_comp_name(Sdr sdr, Address eltData, void *dataBuffer);

when you provide it, this function gets automatically called by whichever sdrlist function you invoked. when it's called, it's passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, dataBuffer, which is nominally the address in local memory of some other item in the same format. the user-supplied function normally compares some key values of the two data items and returns:

  • 0 if they are equal
  • an integer less than 0 if eltData's key value is less than that of dataBuffer
  • an integer greater than 0 if eltData's key value is greater than that of dataBuffer

these return values will produce a list in ascending order. ⭐ if you want the list in descending order, the function must reverse the signs of these return values. yes, manually. that's the deal.

when deleting an element or destroying a list, you may optionally provide a delete function shaped like this:

void user_delete_name(Sdr sdr, Address eltData, void *argData)

when you provide it, this function gets automatically called by whichever sdrlist function you invoked. when it's called, it's passed the content of a list element (eltData, nominally the Address of an item in the SDR's heap space) and an argument, argData, which — if non-NULL — is normally the address in local memory of a data item providing context for the list element deletion. the user-supplied function performs any application-specific cleanup associated with deleting the element, such as freeing the element's content data item and/or other SDR heap space associated with the element. 🧚 clean up after yourself, it's giving responsible.

🌈 SEE ALSO 🌈

go read those too, bestie, they're all part of the same friend group 🫶

and that's the whole page!! this one was generated by perl v5.24.1 and dated 2016-07-07 — so yeah she's an elder but she still ate 💅✨ slay, no cap, go build some doubly-linked lists 👑💖

📦 where this page comes from