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