第三十三章 Caché 函数大全 $LISTNEXT 函数
大纲
从列表中顺序检索元素。
参数
- list 任何计算结果为列表的表达式。
- ptr 指向列表中下一个元素的指针。必须将ptr指定为初始化为0的局部变量。此值指向列表的开头。 Caché使用内部地址值算法（不是可预测的整数计数器）来递增ptr。因此，可用于设置ptr的唯一值是0。ptr不能是全局变量或下标变量。
- value 用于保存列表元素的数据值的局部变量。调用
$LISTNEXT之前不必初始化value。值不能是全局变量或下标变量。
描述
$LISTNEXT顺序返回列表中的元素。在第一次调用$LISTNEXT之前将ptr初始化为0。这将导致$LISTNEXT从列表的开头开始返回元素。 $LISTNEXT的每次连续调用都会提高ptr值，并将下一个列表元素值返回给value。$LISTNEXT函数返回1，表示已成功检索列表元素。
当$LISTNEXT到达列表的末尾时，它返回0，将ptr重置为0，并使值与上一次调用保持不变。因为ptr已重置为0，所以$LISTNEXT的下一次调用将在列表的开头开始。
注意：由于ptr是列表内部结构的索引，因此在$LISTNEXT上使用列表时，不应修改列表。修改列表可能会使ptr值无效，并导致下一次调用$LISTNEXT发出<FUNCTION>错误。
可以使用$LISTVALID来确定list是否为有效列表。无效的列表会导致$LISTNEXT生成错误。
当$LISTNEXT遇到省略的列表元素（值为null的元素）时，它返回1表示已成功检索列表元素，将ptr前进到下一个元素，并将值重置为未定义的变量。当遇到省略的列表元素时，例如在list=$LB("a",,"b"),上第二次调用LB()
,list=LB(,)`.
$LISTNEXT("",ptr,value)返回0，并且不前进指针或设置值。 $LISTNEXT($LB(""),ptr,value)返回1，使指针前进，并将value设置为空字符串（“”）。
$LISTNEXT和性能
Caché 列表是处理大量数据值的最有效方法。由于长字符串默认情况下处于活动状态，因此可以使用列表来保存大量要处理的值，而不是使用数组或其他数据结构。与使用$LIST执行相同的操作相比，使用$LISTNEXT从列表返回大量元素要有效得多。
以下示例快速访问mylist中的元素：
SET ptr=0
WHILE $LISTNEXT(mylist,ptr,value) {
/* perform some operation on value */
}
它大大快于以下等效示例：
FOR i=1:1:$LISTLENGTH(mylist) {
SET value=$LIST(mylist,i)
/* perform some operation on value */
}
$LISTNEXT和嵌套列表
以下示例返回三个元素，因为$LISTNEXT无法识别嵌套列表中的单个元素：
/// d ##class(PHA.TEST.Function).LISTNEXT()
ClassMethod LISTNEXT()
{
SET list=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan"))
SET ptr=0,count=0
WHILE $LISTNEXT(list,ptr,value) {
SET count=count+1
WRITE !,value
}
WRITE !,"列表结果: ",count," 元素被找到"
QUIT
}
DHC-APP>d ##class(PHA.TEST.Function).LISTNEXT()
Apple
Pear
WalnutPecan
列表结果: 3 元素被找到
示例
以下示例顺序返回列表中的所有元素。 $SELECT遇到省略的元素时，将返回默认值“omitted”：
/// d ##class(PHA.TEST.Function).LISTNEXT1()
ClassMethod LISTNEXT1()
{
SET list=$LISTBUILD("Red","Blue",,"Green")
SET ptr=0,count=0
WHILE $LISTNEXT(list,ptr,value) {
SET count=count+1
WRITE !,count,": ",$SELECT($DATA(value):value,1:"omitted")
}
WRITE !,"列表结果: ",count," 元素被找到"
QUIT
}
DHC-APP>d ##class(PHA.TEST.Function).LISTNEXT1()
1: Red
2: Blue
3: omitted
4: Green
列表结果: 4 元素被找到
