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 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 <ko@cs.ubc.ca>
Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>