第三十三章 Caché 函数大全 $LISTNEXT 函数 第三十三章 Caché 函数大全 $LISTNEXT 函数 大纲 描述 示例

第三十三章 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 元素被找到