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>