.ds Vv 1.2.14 .TH VistaIOList 3 "3 June 1994" "VistaIO Version \*(Vv" .SH NAME VistaIOList \- representation of a list of opaque items .SH SYNOPSIS .nf .B #include .PP .B VistaIOList \fIvlist\fP; .PP .B VistaIOList VistaIOListCreate (void); .PP .B int VistaIOListCount (VistaIOList \fIvlist\fP); .PP .B VistaIOPointer VistaIOListFirst (VistaIOList \fIvlist\fP); .PP .B VistaIOPointer VistaIOListLast (VistaIOList \fIvlist\fP); .PP .B VistaIOPointer VistaIOListNext (VistaIOList \fIvlist\fP); .PP .B VistaIOPointer VistaIOListPrev (VistaIOList \fIvlist\fP); .PP .B VistaIOPointer VistaIOListCurr (VistaIOList \fIvlist\fP); .PP .B void VistaIOListAdd (VistaIOList \fIvlist\fP, VistaIOPointer \fIitem\fP); .PP .B void VistaIOListInsert (VistaIOList \fIvlist\fP, VistaIOPointer \fIitem\fP); .PP .B void VistaIOListAppend (VistaIOList \fIvlist\fP, VistaIOPointer \fIitem\fP); .PP .B void VistaIOListPrepend (VistaIOList \fIvlist\fP, VistaIOPointer \fIitem\fP); .PP .B VistaIOPointer VistaIOListRemove (VistaIOList \fIvlist\fP); .PP .B void VistaIOListConcat (VistaIOList \fIvlist1\fP, VistaIOList \fIvlist2\fP); .PP .B void VistaIOListDestroy (VistaIOList \fIvlist\fP, void (*\fIitem_free\fP)()); .PP .B VistaIOPointer VistaIOListTrim (VistaIOList \fIvlist\fP); .PP .B "VistaIOPointer VistaIOListSearch (VistaIOList \fIvlist\fP, int (*\fIcomp\fP)(), VistaIOPointer \fIcomp_arg\fP);" .PP .B VistaIOPointer VistaIOListGetCurr (VistaIOList \fIvlist\fP); .PP .B void VistaIOListSetCurr (VistaIOList \fIvlist\fP, VistaIOPointer \fIcurr\fP); .fi .SH DESCRIPTION .SS Introduction The \fBVistaIOList\fP data type and its associated routines allow programmers to create and manipulate lists of opaque items. A \fBVistaIOList\fP is an ordered list whose elements are pointers to opaque data structures. .PP The elements of a \fBVistaIOList\fP are arranged in a sequential order so that it is meaningful to say that an element is before (or after) another element. A \fBVistaIOList\fP 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). .PP A \fBVistaIOList\fP also has the notion of a \fIcurrent item\fP. The current item of a \fBVistaIOList\fP 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 \fBNULL\fP if it is the pseudo-element BEFORE-ALL or AFTER-ALL. .SS "Routines and Macros" \fBVistaIOListCreate\fP creates an empty \fBVistaIOList\fP, makes BEFORE-ALL the current item, and returns the new \fBVistaIOList\fP. .PP \fBVistaIOListCount\fP returns the number of elements in \fIvlist\fP. .PP \fBVistaIOListFirst\fP makes the first element of \fIvlist\fP the current item if \fIvlist\fP is not empty, and makes BEFORE-ALL the current item otherwise. It returns the value of the new current item. .PP \fBVistaIOListLast\fP makes the last element of \fIvlist\fP the current item if \fIvlist\fP is not empty, and makes AFTER-ALL the current item otherwise. It returns the value of the new current item. .PP \fBVistaIOListNext\fP makes the element after the current item of \fIvlist\fP the new current item, and returns the value of the new current item. .PP \fBVistaIOListPrev\fP makes the element before the current item of \fIvlist\fP the new current item, and returns the value of the new current item. .PP \fBVistaIOListCurr\fP returns the value of the current item of \fIvlist\fP. .PP \fBVistaIOListAdd\fP adds \fIitem\fP to \fIvlist\fP immediately after the current item if the current item is not AFTER-ALL. Otherwise, \fIitem\fP is added to \fIvlist\fP immediately before AFTER-ALL. \fBVistaIOListAdd\fP makes \fIitem\fP the new current item. .PP \fBVistaIOListInsert\fP adds \fIitem\fP to \fIvlist\fP immediately before the current item if the current item is not BEFORE-ALL. Otherwise, \fIitem\fP is added to \fIvlist\fP immediately after BEFORE-ALL. \fBVistaIOListInsert\fP makes \fIitem\fP the new current item. .PP \fBVistaIOListAppend\fP adds \fIitem\fP to \fIvlist\fP immediately before AFTER-ALL, and makes \fIitem\fP the new current item. .PP \fBVistaIOListPrepend\fP adds \fIitem\fP to \fIvlist\fP immediately after BEFORE-ALL, and makes \fIitem\fP the new current item. .PP \fBVistaIOListRemove\fP returns \fBNULL\fP if the current item of \fIvlist\fP is either BEFORE-ALL or AFTER-ALL. Otherwise, \fBVistaIOListRemove\fP removes the current item from \fIvlist\fP, returns the value of the element being removed, and makes the element after the original current item the new current item. .PP \fBVistaIOListConcat\fP concatenates \fIvlist2\fP to the end of \fIvlist1\fP. If the current item of \fIvlist1\fP is AFTER-ALL, then \fBVistaIOListConcat\fP will make the element after BEFORE-ALL of \fIvlist2\fP the current item of the concatenated list; otherwise, the current item of \fIvlist1\fP will become the current item of the concatenated list. The concatenated list will be stored in \fIvlist1\fP, and \fIvlist2\fP will cease to exist after the concatenation. .PP \fBVistaIOListDestroy\fP frees all the storage area occupied by \fIvlist\fP, including the storage area occupied by the opaque data objects pointed to by the elements of \fIvlist\fP. \fIitem_free\fP is a pointer to a function that knows how to free an opaque data object. \fIitem_free\fP must have the following prototype: .RS \fBvoid \fIitem_free\fP (VistaIOPointer \fIopaque_object\fP)\fP .RE \fRwhere \fIopaque_object\fP is the object to be freed. .PP \fBVistaIOListTrim\fP removes the last element of \fIvlist\fP, returns the value of the element being removed, and makes the new last element the current item (by calling \fBVistaIOListLast\fP) if \fIvlist\fP is not empty. Otherwise, \fBVistaIOListTrim\fP makes AFTER-ALL the current item and returns \fBNULL\fP. .PP \fBVistaIOListSearch\fP searches for the first occurrence (starting from the current item) of an element \fIe\fP in \fIvlist\fP such that a call to (*\fIcomp\fP)(\fIe\fP, \fIcomp_arg\fP) returns a non-zero value. If such an element exists, \fBVistaIOListSearch\fP makes that element the current item and returns the value of that element. Otherwise, \fBVistaIOListSearch\fP makes AFTER-ALL the current item and returns \fBNULL\fP. .PP \fBVistaIOListGetCurr\fP returns an opaque pointer denoting the current item. This pointer is only intended for use in a subsequent invocation of \fBVistaIOListSetCurr\fP. .PP \fBVistaIOListSetCurr\fP sets the identity of the current item using a value previously supplied by \fBVistaIOListGetCurr\fP. Care must be taken to ensure that this isn't an item that has been removed from the list since \fBVistaIOListGetCurr\fP was used. .SH "SEE ALSO" .SH AUTHOR Daniel Ko Adaption to vistaio: Gert Wollny