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>

VistaIO Version 1.2.14                             3 June 1994                                    VistaIOList(3)