概要
$LISTNEXT は、list 内の要素を順番に返します。ユーザは、$LISTNEXT の初回呼び出しの前に、ptr を 0 に初期化します。これにより、$LISTNEXT はリストの先頭から要素を返し始めます。$LISTNEXT の連続する呼び出しごとに ptr が進められ、次のリストの要素値が value に返されます。$LISTNEXT 関数は 1 を返し、リスト要素の取得に成功したことを示します。
$LISTNEXT がリストの最後に到達したときは、0 を返し、ptr を 0 にリセットします。value は前の呼び出しから変更されません。ptr は 0 にリセットされているので、$LISTNEXT の次回の呼び出しは、list の最初から開始されます。
Note:
ptr は list の内部構造のインデックスであるため、$LISTNEXT の使用中にリストを変更することはできません。list を変更すると、ptr の値が無効になり、次に $LISTNEXT を呼び出したときに <FUNCTION> エラーが発生する可能性があります。
$LISTVALID を使用すると、list が有効なリストかどうかを判定できます。無効なリストの場合、$LISTNEXT で <LIST> エラーが発生します。
$LISTNEXT が省略されたリスト要素 (NULL 値を持つ要素) を検出すると、1 を返します。これは、リスト要素の取得が成功し、ptr を次の要素に進め、value を未定義の変数にリセットすることを示します。これは、list=$LB("a",,"b") で $LISTNEXT を 2 回目に呼び出した場合や、有効なリストである list=$LB()、list=$LB(UndefinedVar)、または list=$LB(,) を使用した場合など、省略されたリスト要素を検出したときに発生する可能性があります。
$LISTNEXT("",ptr,value) は 0 を返し、ポインタを進めたり value を設定することはありません。$LISTNEXT($LB(""),ptr,value) は 1 を返し、ポインタを進め、value を NULL 文字列 ("") に設定します。
例
次の例は、リスト内のすべての要素を順番に返します。省略された要素を検出した場合、$SELECT は既定値 “omitted” を返します。
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 !,"End of list: ",count," elements found"
QUIT