$LISTFIND ($LF)

Searches a specified list for the requested value.

Synopsis

$LISTFIND(list,value,startafter)
$LF(list,value,startafter)

Parameters

list	An expression that resolves to a Caché list. A Caché list is created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
value	An expression that resolves to the desired element value.
startafter	Optional — An expression that resolves to a positive integer, specifying a position in list. The search starts with the element after this position.

Description

$LISTFIND 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 parameter, $LISTFIND 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.

Examples

The following example returns 2, the position of the first occurrence of the requested string:

x=$LISTBUILD("A","B","C","D")
PRINT $LISTFIND(x,"B")

The following example returns 0, indicating the requested string was not found:

x=$LISTBUILD("A","B","C","D")
PRINT $LISTFIND(x,"E")

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 position:

x=$LISTBUILD("A","B","C","D")
PRINT $LISTFIND(x,"B",2)

The second example finds the second occurrence of the requested string and returns 4, because the first occurs before the startafter position:

y=$LISTBUILD("A","B","C","A")
PRINT $LISTFIND(y,"A",2)

The $LISTFIND 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")
PRINT $LISTFIND(mylist,"B")

Notes

Invalid Parameter Values

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.