Traversing Lists

InstallShield 2020

InstallShield provides these functions for traversing lists incrementally and non-incrementally:

Functions that Are Used to Traverse Lists

Function	Description
ListCount	Sees how many string or numeric elements are contained in a specified list.
ListCurrentItem	Returns the current item in the list.
ListCurrentString	Returns the current string in the list.
ListFindItem	Attempts to find a numeric element in a list. If found, the element becomes the current element of the list.
ListFindString	Attempts to find a string element in a list. If found, the element becomes the current element of the list.
ListGetFirstItem	Retrieves the first element from a number list.
ListGetFirstString	Retrieves the first string from a string list.
ListGetNextItem	Retrieves the element after the current element from a number list.
ListGetNextString	Retrieves the element after the current element from a string list.
ListSetIndex	Sets the current element of the list as an index.

InstallShield uses single-linked lists, which means that unless you use functions that set indices or search for specific elements in lists, you can traverse lists incrementally in one direction only: from the first element to the last.

InstallShield allows you to traverse lists in non-incremental fashion by means of indices and by searching for particular elements in lists. Refer to the individual function descriptions for more details.

Most list traversing and list access operations are carried out relative to the current list element. Furthermore, most of the functions used to traverse and access lists establish a current element as a result of their action. Therefore, making an element the current element in a list is not an isolated action; it is a byproduct of another action.

If a list is empty, adding an element to the list will establish a current element. If a list is not empty, then making an element the current element is best accomplished by traversing the list or searching for a particular element in the list.

Tip:Lists are often processed within while loops, usually checking for END_OF_LIST. An infinite loop can result if the list is not valid. If you are processing lists in a while loop, make sure that you have created the list with the ListCreate function, and that you have not destroyed the list with the ListDestroy function.