$LISTDATA (ObjectScript)
構文
$LISTDATA(list,position,var)
$LD(list,position,var)
引数
引数 | 説明 |
---|---|
list | 有効なリストに評価する式 |
position | オプション — 指定したリストで、位置として解釈される式ゼロでない正の整数または -1 です。 |
var | オプション — 指定されたリスト位置にある要素値を含む変数。$LISTDATA が値 1 を返す場合、var が書き込まれます。$LISTDATA が値 0 を返す場合、var は変更されません。 |
概要
$LISTDATA は、リスト内の指定された要素のデータを調べ、ブーリアン値を返します。position 引数で指定された要素が list に存在し、データ値を持つ場合、$LISTDATA は値 1 を返します。要素が list に存在しないか、またはデータ値を持たない場合、$LISTDATA は値 0 を返します。
$LISTDATA は、オプションで要素値を var 変数に書き込むことができます。
$LISTDATA をループ構造内で使用して、複数の連続した要素値を返さないでください。$LISTDATA は実行ごとにリストを最初から評価する必要があるため、これが動作している間、非常に効率が悪くなります。複数の連続した要素値を返す場合、$LISTNEXT 関数を使用した方がはるかに効率的です。
引数
list
list は、複数の要素を含むエンコードされた文字列です。list は $LISTBUILD または $LISTFROMSTRING を使用して作成されるか、あるいは $LIST を使用して別のリストから抽出されなければなりません。
$LISTVALID 関数を使用すると、式が有効なリストであるかどうかを判定できます。list 引数内の式が有効なリストとして評価されない場合は、<LIST> エラーが発生します。有効なリストの指定された位置にデータが含まれていない場合、$LISTDATA は 0 を返します。
position
1 からカウントするリスト内の要素の整数位置。position 引数を省略した場合、$LISTDATA は先頭要素を評価します。position 引数の値が -1 の場合は、リストの最終要素を指定するのと同じ意味です。
position が存在しないリスト・メンバを参照する場合、$LISTDATA は 0 を返します。0 のposition は常に 0 を返します。position の値が -1 未満の場合に $LISTDATA 関数を呼び出すと、<RANGE> エラーが発生します。
var
$LISTDATA が値 1 を返す場合、InterSystems IRIS は、要求された要素の値を var に書き込みます。$LISTDATA が値 0 を返す場合、var は変更されません。var 引数は、添え字付きもしくは添え字なしのローカル、グローバル、またはプロセス・プライベート・グローバル変数のいずれかにできます。これを定義する必要はありません。1 を返す $LISTDATA の最初の呼び出しにより var の定義と設定が行われます。$LISTDATA の最初の呼び出しが 0 を返す場合、var は未定義のままになります。
var 引数は、非多次元オブジェクト・プロパティとすることはできません。非多次元オブジェクト・プロパティに値を書き込もうとすると、<OBJECT DISPATCH> エラーが発生します。
var 引数は、特殊変数とすることはできません。 特殊変数に値を書き込もうとすると、<SYNTAX> エラーが発生します。
例
以下の 2 つの例では、position 引数にさまざまな値を指定した結果を示します。
以下の $LISTDATA 文は、0 を返します。
KILL y
SET x=$LISTBUILD("Red",,y,"","Green",)
WRITE !,$LISTDATA(x,2) ; second element is undefined
WRITE !,$LISTDATA(x,3) ; third element is a killed variable
WRITE !,$LISTDATA(x,-1) ; the last element is undefined
WRITE !,$LISTDATA(x,0) ; the 0th position
WRITE !,$LISTDATA(x,6) ; 6th position in 5-element list
以下の $LISTDATA 文は、1 を返します。
SET x=$LISTBUILD("Red",,y,"","Green",)
WRITE !,$LISTDATA(x) ; first element (by default)
WRITE !,$LISTDATA(x,1) ; first element specified
WRITE !,$LISTDATA(x,4) ; fourth element, value=null string
WRITE !,$LISTDATA(x,5) ; fifth element
以下の 3 引数の $LISTDATA 文は、要素値の存在についてテストし、evalue 変数をその値で更新します。$LISTDATA が 0 を返す場合、evalue は変更されないままであることに注意してください。
SET x=$LISTBUILD("Red",,y,"","Green",)
FOR i=1:1:$LISTLENGTH(x) {
WRITE "element ",i," data? ",$LISTDATA(x,i,evalue)," value ",evalue,!
}
WRITE i," list elements"
以下のすべての $LISTDATA 文は、0 を返します。
WRITE !,$LISTDATA($LB()) ; null list
WRITE !,$LISTDATA($LB(UndefinedVar)) ; null list
WRITE !,$LISTDATA("") ; null string is a valid list
; but contain no data
WRITE !,$LISTDATA($LB(,)) ; two-element null list
以下の $LISTDATA 文は、1 を返します。
WRITE !,$LISTDATA($LB("")) ; data is null string
WRITE !,$LISTDATA($LB($CHAR(0))) ; data is non-display character
関連項目
-
$LIST 関数
-
$LISTBUILD 関数
-
$LISTFIND 関数
-
$LISTGET 関数
-
$LISTLENGTH 関数
-
$LISTSAME 関数
-
$LISTUPDATE 関数
-
$LISTVALID 関数