--- name: "VistaIOList" section: "3" platform: "linux" package: "libvistaio-dev" version: "1.2.19-3+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/VistaIOList" --- # VistaIOList(3) representation of a list of opaque items ## NAME VistaIOList - representation of a list of opaque items ## SYNOPSIS ``` #include ``` **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 associated routines allow programmers to create and manipulate lists of opaque items. A **VistaIOList** is an ordered list whose elements are pointers to opaque data structures. The elements of a **VistaIOList** are arranged in a sequential order so that it is meaningful to say that an element is before (or after) another element. A **VistaIOList** has two pseudo-elements: BEFORE-ALL and AFTER-ALL. BEFORE-ALL is located before all other elements of the list. The element before BEFORE-ALL is still BEFORE-ALL itself; the element after BEFORE-ALL is the first element of the list (or AFTER-ALL if the list is empty). Similarly, AFTER-ALL is located after all other elements of the list. The element after AFTER-ALL is 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 of a **VistaIOList** may be a particular element of the list, the pseudo-element BEFORE-ALL, or the pseudo-element AFTER-ALL. The value of the current item is simply the value of the element it represents, or **NULL** if it is the pseudo-element BEFORE-ALL or AFTER-ALL. ### Routines and Macros **VistaIOListCreate** creates an empty **VistaIOList**, makes BEFORE-ALL the current item, and returns the new **VistaIOList**. **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. **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**. **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. ## SEE ALSO ## AUTHOR Daniel Ko \ Adaption to vistaio: Gert Wollny \