VistaIOList (3)

#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);

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.

Daniel Ko <[email protected]>

Adaption to vistaio: Gert Wollny <[email protected]>