Article Directory

Chapter 29 Caché Function Collection $LISTFIND Function
Outline
- parameter
description
- Empty Strings 与 Empty Lists
Example

Chapter 29 Caché Function Collection $LISTFIND Function

Search for the required value in the specified list.

Outline

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

parameter

The result of list calculation is an expression of a valid list. A list is an encoded string containing one or more elements. You must use $LISTBUILDor $LISTFROMSTRINGcreate a list, or use $LISTto extract a list from another list.
value contains the expression of the desired element value.
startafter optional-interpreted as an integer expression for the position of the list. The search starts from the element after that position; therefore, 0 means starting from position 1, and 1 means starting from position 2. startafter = -1 is a valid value, but no match is always returned. Only the integer part of the startafter value is used.

description

$LISTFINDSearch for the first instance of the requested value in the specified list. The match must be precise and contain the complete element value. Letter comparison is case sensitive. The numbers are compared in canonical form. If an exact match is found, $LISTFINDthe position of the matched element is returned. If no value is found, $LISTFIND0 is returned.

The search starts from the element after the position indicated by the startafter parameter. If the startafter parameter is omitted, the $LISTFINDstartafter value is assumed to be 0, and the search starts from the first element (element 1).

If no match is found, $LISTFIND0 is returned. If the value of the startafter parameter refers to a non-existent list member, it will $LISTFINDalso return 0.

You can use $LISTVALIDfunctions to determine whether the list is a valid list. If the list is not a valid list, the system generates <LIST>an error.

If the value of the startafter parameter is less than -1, the call to the $LISTFINDfunction will generate an error.

Empty Strings 与 Empty Lists

$LISTFINDFunctions can be used to find empty string values, as shown in the following example:

DHC-APP> SET x=$LISTBUILD("A","","C","D")
 
DHC-APP> WRITE $LISTFIND(x,"")   ; returns 2
2

$LISTFINDCan be used with lists containing omitted elements, but cannot be used to locate omitted elements. The following example finds a value in the list that contains omitted elements:

   SET x=$LISTBUILD("A",,"C","D")
  WRITE $LISTFIND(x,"C")   ; returns 3

The following $LISTFINDexample returns 1:

DHC-APP>  WRITE $LISTFIND($LB(""),"")   ; returns 1
1

The following $LISTFINDexample returns 0:

DHC-APP>WRITE $LISTFIND("",""),!
0
 
DHC-APP>WRITE $LISTFIND($LB(),""),!
0

The following example list contains an empty list that is concatenated with a list that contains data. Adding before the empty list will change the list position of the element in the final concatenated list:

/// d ##class(PHA.TEST.Function).LISTFIND()
ClassMethod LISTFIND()
{
    
    
	SET x=$LISTBUILD("A","B","C","D")
	WRITE $LISTFIND(x,"B"),!         ; returns 2
	WRITE $LISTFIND(""_x,"B"),!      ; returns 2
	WRITE $LISTFIND($LB()_x,"B"),!   ; returns 3
	WRITE $LISTFIND($LB(,,,)_x,"B")  ; returns 6
}

DHC-APP>d ##class(PHA.TEST.Function).LISTFIND()
2
2
3
6

However, concatenating an empty string to a value pair is $LISTFINDinvalid:

/// d ##class(PHA.TEST.Function).LISTFIND1()
ClassMethod LISTFIND1()
{
    
    
	SET x=$LISTBUILD("A","B","C","D")
	WRITE $LISTFIND(x,"B"),!      ; returns 2
	WRITE $LISTFIND(x,"B"_""),!   ; returns 2
	WRITE $LISTFIND(x,""_"B"),!   ; returns 2
}

DHC-APP>d ##class(PHA.TEST.Function).LISTFIND1()
2
2
2

Example

The following example returns 2, which is the position where the requested string first appears:

DHC-APP>SET x=$LISTBUILD("A","B","C","D")
 
DHC-APP>WRITE $LISTFIND(x,"B")
2

The following example returns 0, indicating that the requested string could not be found:

DHC-APP>SET x=$LISTBUILD("A","B","C","D")
 
DHC-APP>WRITE $LISTFIND(x,"E")
0

The following example shows the effect of using the startafter parameter. The first example cannot find the requested string and returns 0 because it appears in the startafter position:

DHC-APP>SET x=$LISTBUILD("A","B","C","D")
 
DHC-APP>WRITE $LISTFIND(x,"B",2)
0

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

DHC-APP>SET y=$LISTBUILD("A","B","C","A")
 
DHC-APP>WRITE $LISTFIND(y,"A",2)
4

$LISTFINDThe function matches only complete elements. Therefore, the following example returns 0 because all elements in the list are not equal to the string "B", even though all elements contain "B":

DHC-APP>SET mylist = $LISTBUILD("ABC","BCD","BBB")
 
DHC-APP>WRITE $LISTFIND(mylist,"B")
0

The following number examples all return 0 because the numbers have been converted to canonical form before matching. In these cases, the string numeric value and the canonical form number do not match:

/// d ##class(PHA.TEST.Function).LISTFIND2()
ClassMethod LISTFIND2()
{
    
    
	SET y=$LISTBUILD("1.0","+2","003","2*2")
	WRITE $LISTFIND(y,1.0),!
	WRITE $LISTFIND(y,+2),!
	WRITE $LISTFIND(y,003),!
	WRITE $LISTFIND(y,4)
}

DHC-APP>d ##class(PHA.TEST.Function).LISTFIND2()
0
0
0
0

The following numeric examples match because numeric values are compared in canonical form:

/// d ##class(PHA.TEST.Function).LISTFIND3()
ClassMethod LISTFIND3()
{
    
    
	SET y=$LISTBUILD(7.0,+6,005,2*2)
	WRITE $LISTFIND(y,++7.000),!   ; returns 1
	WRITE $LISTFIND(y,0006),!      ; returns 2
	WRITE $LISTFIND(y,8-3),!       ; returns 3
	WRITE $LISTFIND(y,--4.0)       ; returns 4
}

DHC-APP>d ##class(PHA.TEST.Function).LISTFIND3()
1
2
3
4

The following examples all return 0 because the specified startafter value does not match:

/// d ##class(PHA.TEST.Function).LISTFIND4()
ClassMethod LISTFIND4()
{
    
    
	SET y=$LISTBUILD("A","B","C","D")
	WRITE $LISTFIND(y,"A",1),!
	WRITE $LISTFIND(y,"B",2),!
	WRITE $LISTFIND(y,"B",99),!
	WRITE $LISTFIND(y,"B",-1)
}

DHC-APP>d ##class(PHA.TEST.Function).LISTFIND4()
0
0
0
0

The following example shows how to use $LISTFINDfind nested lists. Note that Caché treats a multi-element nested list as a single list element with a list value:

DHC-APP> SET y=$LISTBUILD("A",$LB("x","y"),"C","D")
 
DHC-APP> WRITE $LISTFIND(y,$LB("x","y"))
2