Searches a specified list for the requested value.
||An expression that resolves to a Caché list. A Caché list is created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
||An expression that resolves to the desired element value.
||Optional An expression that resolves to a positive integer, specifying a position in list. The search starts with the element after this position.
searches the specified list
for the first instance of the requested value
. The search begins with the element after the position indicated by the startafter
parameter. If you omit the startafter
assumes a startafter
value of 0 and starts the search with the first element (element 1). If the value is found, $LISTFIND
returns the position of the matching element. If the value is not found, $LISTFIND
returns a 0. The $LISTFIND
function will also return a 0 if the value of the startafter
parameter refers to a nonexistent list member.
The following example returns 2, the position of the first occurrence of the requested string:
The following example returns 0, indicating the requested string was not found:
The following examples show the effect of using the startafter
parameter. The first example does not find the requested string and returns 0 because it occurs at the startafter
The second example finds the second occurrence of the requested string and returns 4, because the first occurs before the startafter
function only matches complete elements. Thus, the following example returns 0 because no element of the list is equal to the string B, though all of the elements contain B:
mylist = $LISTBUILD("ABC","BCD","BBB")
If the expression in the list
parameter does not evaluate to a valid list, a <LIST> error occurs.
If the value of the startafter
parameter is less than -1, invoking the $LISTFIND
function generates a <RANGE> error.