第二十九章 Caché 函数大全 $LISTFIND 函数
在指定的列表中搜索所需的值。
大纲
$LISTFIND(list,value,startafter)
$LF(list,value,startafter)
参数
- list 计算结果为有效列表的表达式。列表是包含一个或多个元素的编码字符串。必须使用
$LISTBUILD或$LISTFROMSTRING创建一个列表，或者使用$LIST从另一个列表中提取一个列表。 - value 包含所需元素值的表达式。
- startafter 可选-解释为列表位置的整数表达式。搜索从该位置之后的元素开始；因此，0表示从位置1开始，1表示从位置2开始。startafter = -1是有效值，但始终不返回匹配项。仅使用startafter值的整数部分。
描述
$LISTFIND在指定的列表中搜索请求值的第一个实例。匹配项必须精确且包含完整的元素值。字母比较区分大小写。数字以规范形式进行比较。如果找到完全匹配的内容，则$LISTFIND返回匹配元素的位置。如果找不到值，则$LISTFIND返回0。
搜索从startafter参数指示的位置之后的元素开始。如果省略startafter参数，则$LISTFIND假定startafter值为0，并从第一个元素（元素1）开始搜索。
如果找不到匹配项，则$LISTFIND返回0。如果startafter参数的值引用不存在的列表成员，则$LISTFIND也将返回0。
可以使用$LISTVALID函数来确定列表是否为有效列表。如果列表不是有效列表，则系统生成<LIST>错误。
如果startafter参数的值小于-1，则调用$LISTFIND函数将产生错误。
Empty Strings 与 Empty Lists
$LISTFIND函数可用于查找空字符串值，如以下示例所示：
DHC-APP> SET x=$LISTBUILD("A","","C","D")
DHC-APP> WRITE $LISTFIND(x,"") ; returns 2
2
$LISTFIND可以与包含省略的元素的列表一起使用，但是不能用于定位省略的元素。下面的示例在列表中找到一个包含省略元素的值：
SET x=$LISTBUILD("A",,"C","D")
WRITE $LISTFIND(x,"C") ; returns 3
以下$LISTFIND示例返回1：
DHC-APP> WRITE $LISTFIND($LB(""),"") ; returns 1
1
以下$LISTFIND示例返回0：
DHC-APP>WRITE $LISTFIND("",""),!
0
DHC-APP>WRITE $LISTFIND($LB(),""),!
0
以下示例列表包含一个空列表，该空列表与包含数据的列表连接在一起。在空列表前添加将更改元素在最终的串联列表中的列表位置：
/// 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
但是，将空字符串连接到value对$LISTFIND无效：
/// 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
示例
以下示例返回2，即所请求的字符串首次出现的位置：
DHC-APP>SET x=$LISTBUILD("A","B","C","D")
DHC-APP>WRITE $LISTFIND(x,"B")
2
下面的示例返回0，指示找不到请求的字符串：
DHC-APP>SET x=$LISTBUILD("A","B","C","D")
DHC-APP>WRITE $LISTFIND(x,"E")
0
以下示例显示了使用startafter参数的效果。第一个示例找不到请求的字符串并返回0，因为该字符串出现在startafter位置：
DHC-APP>SET x=$LISTBUILD("A","B","C","D")
DHC-APP>WRITE $LISTFIND(x,"B",2)
0
第二个示例查找请求的字符串的第二个出现并返回4，因为第一个出现在startafter位置之前：
DHC-APP>SET y=$LISTBUILD("A","B","C","A")
DHC-APP>WRITE $LISTFIND(y,"A",2)
4
$LISTFIND函数仅匹配完整的元素。因此，以下示例返回0，因为列表中的所有元素都不等于字符串“B”，尽管所有元素都包含“B”：
DHC-APP>SET mylist = $LISTBUILD("ABC","BCD","BBB")
DHC-APP>WRITE $LISTFIND(mylist,"B")
0
以下数字示例均返回0，因为数字在匹配之前已转换为规范形式。在这些情况下，字符串数字值和规范形式号不匹配：
/// 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
以下数字示例匹配，因为数字值以规范形式进行比较：
/// 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
以下示例均返回0，因为指定的startafter值不匹配：
/// 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
以下示例显示了如何使用$LISTFIND查找嵌套列表。请注意，Caché将多元素嵌套列表视为具有列表值的单个列表元素：
DHC-APP> SET y=$LISTBUILD("A",$LB("x","y"),"C","D")
DHC-APP> WRITE $LISTFIND(y,$LB("x","y"))
2