$LISTNEXT

リストから要素を順番に取得します。

Synopsis

$LISTNEXT(list,ptr,value)

パラメータ

list	リストに評価する任意の式。
ptr	リスト内の次の要素に対するポインタ。ptr は、0 に初期化されたローカル変数として指定する必要があります。この値は list の先頭を指し示します。Caché は、内部のアドレス値アルゴリズム (予測可能な整数カウンタではない) を使用して ptr をインクリメントします。したがって、ptr の設定に使用できる値は 0 のみです。ptr をグローバル変数および添え字付き変数にすることはできません。
value	リスト要素のデータ値の保持に使用されるローカル変数。$LISTNEXT を呼び出す前に value を初期化する必要はありません。value をグローバル変数および添え字付き変数にすることはできません。

概要

$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(NULL)、または list=$LB(,) を使用した場合など、省略されたリスト要素を検出したときに発生する可能性があります。

$LISTNEXT("",ptr,value) は 0 を返し、ポインタを進めたり value を設定することはありません。$LISTNEXT($LB(""),ptr,value) は 1 を返し、ポインタを進め、value を NULL 文字列 ("") に設定します。

$LISTNEXT とパフォーマンス

Caché リストは、多数のデータ値を処理する最も効率的な方法です。リストを使用すると、long strings が既定でアクティブになるので、配列や他のデータ構造を使用するよりも処理する値を多く保持できます。$LISTNEXT を使用してリストから多数の要素を返すと、$LIST を使用して同じ操作を実行するよりも大幅に効率的です。

以下の例では、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 が入れ子になっているリストの個々の要素を認識しないため、3 つの要素を返します。

   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 !,"End of list: ",count," elements found"
   QUIT

例

次の例は、リスト内のすべての要素を順番に返します。省略された要素を検出した場合、$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

$LISTNEXT

Synopsis

パラメータ

概要

$LISTNEXT とパフォーマンス

$LISTNEXT と入れ子のリスト

例

関連項目