VistaIOList(3)

💖 VistaIOList(3) 💖

okay so bestie, welcome to the Library Functions Manual page for VistaIOList — aka the glow-up your C code needs when you're juggling a whole squad of pointers and you want them in a specific order. 🦋

✨ NAME ✨

VistaIOList — representation of a list of opaque items 💅

🌸 SYNOPSIS 🌸

#include <vistaio.h>

VistaIOList vlist;

VistaIOList VistaIOListCreate (void);

int VistaIOListCount (VistaIOList vlist);

VistaIOPointer VistaIOListFirst (VistaIOList vlist);

VistaIOPointer VistaIOListLast (VistaIOList vlist);

VistaIOPointer VistaIOListNext (VistaIOList vlist);

VistaIOPointer VistaIOListPrev (VistaIOList vlist);

VistaIOPointer VistaIOListCurr (VistaIOList vlist);

void VistaIOListAdd (VistaIOList vlist, VistaIOPointer item);

void VistaIOListInsert (VistaIOList vlist, VistaIOPointer item);

void VistaIOListAppend (VistaIOList vlist, VistaIOPointer item);

void VistaIOListPrepend (VistaIOList vlist, VistaIOPointer item);

VistaIOPointer VistaIOListRemove (VistaIOList vlist);

void VistaIOListConcat (VistaIOList vlist1, VistaIOList vlist2);

void VistaIOListDestroy (VistaIOList vlist, void (*item_free)());

VistaIOPointer VistaIOListTrim (VistaIOList vlist);

VistaIOPointer VistaIOListSearch (VistaIOList vlist, int (*comp)(), VistaIOPointer comp_arg);

VistaIOPointer VistaIOListGetCurr (VistaIOList vlist);

void VistaIOListSetCurr (VistaIOList vlist, VistaIOPointer curr);

🫶 DESCRIPTION 🫶

🧚 Introduction

The VistaIOList data type and its little friend-group of routines let you, a programmer, create and manipulate lists of opaque items. A VistaIOList is an ordered list whose elements are pointers to opaque data structures. No cap. ✨

The elements of a VistaIOList are arranged in a sequential order, so it's actually meaningful to say one element is before (or after) another element. And here's the iconic part — a VistaIOList has two pseudo-elements: BEFORE-ALL and AFTER-ALL. 👑

• BEFORE-ALL sits before every other element of the list. The element before BEFORE-ALL? Still BEFORE-ALL itself. The element after BEFORE-ALL is the first element of the list — or AFTER-ALL if the list is empty.
• AFTER-ALL sits after every other element of the list. The element after AFTER-ALL? Still AFTER-ALL itself. The element before AFTER-ALL is the last element of the list — or BEFORE-ALL if the list is empty.

A VistaIOList also has the notion of a current item. The current item may be a particular element of the list, or the pseudo-element BEFORE-ALL, or the pseudo-element AFTER-ALL. And the value of the current item is simply the value of the element it represents — or NULL if it's the pseudo-element BEFORE-ALL or AFTER-ALL. 💀 (yes, both of those give you NULL, it's giving "no thoughts, head empty")

🌈 Routines and Macros

• VistaIOListCreate — creates an empty VistaIOList, makes BEFORE-ALL the current item, and returns the new VistaIOList. Baby's first list. 🎀
• VistaIOListCount — returns the number of elements in vlist.
• VistaIOListFirst — makes the first element of vlist the current item if vlist is not empty, and makes BEFORE-ALL the current item otherwise. It returns the value of the new current item.
• VistaIOListLast — makes the last element of vlist the current item if vlist is not empty, and makes AFTER-ALL the current item otherwise. It returns the value of the new current item.
• VistaIOListNext — makes the element after the current item of vlist the new current item, and returns the value of the new current item.
• VistaIOListPrev — makes the element before the current item of vlist the new current item, and returns the value of the new current item.
• VistaIOListCurr — returns the value of the current item of vlist.
• VistaIOListAdd — adds item to vlist immediately after the current item, if the current item is not AFTER-ALL. Otherwise, item is added to vlist immediately before AFTER-ALL. VistaIOListAdd makes item the new current item.
• VistaIOListInsert — adds item to vlist immediately before the current item, if the current item is not BEFORE-ALL. Otherwise, item is added to vlist immediately after BEFORE-ALL. VistaIOListInsert makes item the new current item.
• VistaIOListAppend — adds item to vlist immediately before AFTER-ALL, and makes item the new current item.
• VistaIOListPrepend — adds item to vlist immediately after BEFORE-ALL, and makes item the new current item.
• VistaIOListRemove — returns NULL if the current item of vlist is either BEFORE-ALL or AFTER-ALL. Otherwise, VistaIOListRemove removes the current item from vlist, returns the value of the element being removed, and makes the element after the original current item the new current item.
• VistaIOListConcat — concatenates vlist2 to the end of vlist1. If the current item of vlist1 is AFTER-ALL, then VistaIOListConcat will make the element after BEFORE-ALL of vlist2 the current item of the concatenated list; otherwise, the current item of vlist1 will become the current item of the concatenated list. The concatenated list will be stored in vlist1, and vlist2 will cease to exist after the concatenation. 😭 rip vlist2, you served.
• VistaIOListDestroy — frees all the storage area occupied by vlist, including the storage area occupied by the opaque data objects pointed to by the elements of vlist. item_free is a pointer to a function that knows how to free an opaque data object. item_free must have the following prototype:

void item_free (VistaIOPointer opaque_object)

where opaque_object is the object to be freed.

• VistaIOListTrim — removes the last element of vlist, returns the value of the element being removed, and makes the new last element the current item (by calling VistaIOListLast) if vlist is not empty. Otherwise, VistaIOListTrim makes AFTER-ALL the current item and returns NULL.
• VistaIOListSearch — searches for the first occurrence (starting from the current item) of an element e in vlist such that a call to (*comp)(e, comp_arg) returns a non-zero value. If such an element exists, VistaIOListSearch makes that element the current item and returns the value of that element. Otherwise, VistaIOListSearch makes AFTER-ALL the current item and returns NULL. it's giving detective era 🔍
• VistaIOListGetCurr — returns an opaque pointer denoting the current item. This pointer is only intended for use in a subsequent invocation of VistaIOListSetCurr.
• VistaIOListSetCurr — sets the identity of the current item using a value previously supplied by VistaIOListGetCurr.

⚠️ Care must be taken to ensure that this isn't an item that has been removed from the list since VistaIOListGetCurr was used. fr fr, do NOT skip this one, that's a one-way ticket to undefined-behaviour city 🙈

🔥 SEE ALSO 🔥

nothing here bestie — this section is literally empty in the original, no references listed, no crumbs left behind 🍓

👑 AUTHOR 👑

• Daniel Ko <ko@cs.ubc.ca>
• Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

and that's the whole page!! ty for reading, you ate that 💅✨

VistaIO Version 1.2.14 🌸 3 June 1994 — yes it's vintage, yes it still slays, VistaIOList(3) out 🫶💖