$LISTGET (ObjectScript)

list の要素、または要求された要素が未定義の場合は指定した既定値を返します。

Synopsis

$LISTGET(list,position,default)
$LG(list,position,default)

SET $LISTGET(var1,var2,...)=list
SET $LG(var1,var2,...)=list

引数

引数	説明
list	有効なリストに評価する式
position	オプション — list 内の開始位置を指定する整数コード。許可される値は、n (list の先頭からのカウント)、* (list 内の最後の要素)、および -n (list の末尾から逆向きの相対オフセット・カウント) です。したがって、リスト内の 1 つ目の要素は 1、2 つ目の要素は 2、リスト内の最後の要素はであり、最後から 2 番目の要素は -1 です。position が小数の場合、整数部に切り捨てられます。position が省略されている場合は、既定値の 1 が使用されます。古いコード内でリストの最後の要素を指定するには -1 を使用できます。このような -1 の使用法は非推奨であり、や *-n という相対オフセット構文と組み合わせて使用しないでください。
default	オプション — list 要素が未定義の値を持つときに、返り値を作成する式。default が省略されている場合は、既定値の NULL 文字列 (““) が使用されます。default 値を指定するには position 引数を指定する必要があります。
var	単一の変数、またはコンマ区切りの変数リスト内の変数を指定します。省略された変数に対して、プレースホルダとしてのコンマを指定できます。var には、ローカル、プロセス・プライベート、グローバル、添え字なし、添え字付きなどの種類の変数を指定できます。

概要

$LISTGET には、$LISTGET と SET $LISTGET の 2 つの構文形式があります。

$LISTGET(list,position,default) は、指定したリスト内の要求した要素を返します。position の値が、存在しない要素を参照する場合や、値が未定義の要素を指定する場合は、default の値が返されます。
$LISTGET 関数は、$LIST 関数の 1-引数形式および 2-引数形式とまったく同じですが、$LIST が <NULL VALUE> エラーを発生する条件下では、$LISTGET は既定値を返します。<NULL VALUE> エラーが発生する条件に関する詳細は、"$LIST" 関数の説明を参照してください。
SET $LISTGET(var1,var2,...)=list は、リストから複数の要素を取り出して、変数に取り込みます。これは、SET $LISTBUILD(var1,var2,...)=list に類似しています。これらは、明示的な値が割り当てられていない変数の処理方法において違いがあります。SET $LISTGET は、そういった変数を定義して (これにより <UNDEFINED> エラーが回避されます)、NULL 文字列値を割り当て、前の値があれば上書きします。SET $LISTBUILD はそういった変数を定義することはありません。変数に前の値がない場合は <UNDEFINED> エラーが生成され、変数に前の値がある場合はその値が保持されます。

引数

list

リストは、$LISTBUILD または $LISTFROMSTRING を使用して作成されるか、$LIST を使用して別のリストから抽出されます。NULL 文字列 ("") も、有効なリストと見なされます。$LISTVALID を使用すると、list が有効なリストかどうかを判定できます。無効なリストの場合、$LISTGET で <LIST> エラーが発生します。

position

返されるリスト要素の位置 (要素カウント)。要素は、文字列として返されます。リスト要素は 1 からカウントされます。position が省略されると、$LISTGET は最初の要素を返します。

position が n (正の整数) の場合、$LISTGET は list の先頭から要素をカウントします。position の値が list 内の要素数よりも大きい場合、$LISTGET は default の値を返します。
position が * の場合、$LIST は list 内の最後の要素を返します。
position が *-n (アスタリスクとそれに続く負の整数) の場合、$LIST は list の末尾からの相対オフセット分だけ要素をカウントします。したがって、*-0 はリスト内の最後の要素であり、*-1 は最後から 2 番目のリスト要素 (末尾からのオフセットが 1) です。*-n というオフセットが list の最初の要素の前の位置を指定する場合 (例： 3 つの要素を持つリストに対する *-3)、$LISTGET は default の値を返します。*-n というオフセットがそれよりさらに前の位置を指定する場合は (例： 3 つの要素を持つリストに対する *-4)、InterSystems IRIS は <RANGE> エラーを発行します。
position が 0 または -0 の場合、$LISTGET は default の値を返します。

position 引数の数値部分は整数に評価されます。InterSystems IRIS は、小数を切り捨てて、その整数部分のみにします。position に -1 (リストの最後の要素を示す) を指定することは非推奨であり、新しいコード内では使用しないでください。position の値が -1 より小さい負数である場合は、<RANGE> エラーが発生します。

変数を使用して *-n を指定する場合は、常に、引数自体でアスタリスクと符号文字を指定する必要があります。

*-n の有効な指定内容は以下のとおりです。

  SET count=2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LISTGET(alph,*-count,"blank")

  SET count=-2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LISTGET(alph,*+count,"blank")

default

文字列または数値に評価される式。position によって指定された要素が存在しない場合、$LISTGET は default を返します。この状況が発生する可能性があるのは、position がリストの末尾より後ろである場合、position で値のない要素を指定している場合、position が 0 の場合、または list に要素が含まれていない場合です。ただし、position の値 *-n によって指定された位置が、list の 0 番目の要素より前の場合は、InterSystems IRIS は <RANGE> エラーを発行します。

default 引数を省略すると、既定値として NULL 文字列 () が返されます。

SET $LISTGET

SET コマンドの等号の左側で使用された場合、$LISTGET 関数は、単一の処理でリストから複数の要素を取り出します。構文は、以下のとおりです。

SET $LISTGET(var1,var2,...)=list

SET $LISTGET の var 引数は、コンマで区切られた変数のリストです。これらの変数はそれぞれ、対応する位置にある list 要素の値に設定されます。したがって、var1 は、最初の list 要素の値に設定され、var2 は 2 つ目の list 要素の値に設定されるというようになります。var 引数が既存の変数である必要はありません。変数は、SET $LISTGET によって値に割り当てられるときに、定義されます。

var 引数の数は、list 要素の数より少なくても、多くてもかまいません。未指定の var 値には NULL 文字列値が割り当てられます。前に値が定義されている場合、前の値は NULL 文字列に置換されます。前に変数が定義されていない場合、変数が定義されます。この動作を SET $LISTBUILD と比較してください。余分な list 要素は無視されます。
var 引数と list 要素のいずれかまたは両方に、プレースホルダのコンマで表された、省略された値を含めることができます。省略された var 引数は未定義です。list 要素を省略すると、対応する var 値が NULL 文字列に設定されます。前に値が定義されている場合、前の値は削除されます。前に変数が定義されていない場合、変数が定義されます。この動作を SET $LISTBUILD と比較してください。

SET $LISTGET はアトミック処理です。コンパイル済みのプログラムでの var 引数の最大数は 1024 個です。ターミナルから実行した場合の var 引数の最大数は 128 個です。これらの制限を超過しようとすると、<SYNTAX> エラーが発行されます。

var 引数がオブジェクト・プロパティ (object.property) である場合、プロパティは多次元でなければなりません。すべてのプロパティは、オブジェクト・メソッド内で i%property インスタンス変数として参照できます。

以下の例では、(等号の右側にある) $LISTBUILD によって、4 つの要素を使用してリストが作成されます。

以下の例では、SET $LISTGET によって、リストから最初の 2 つの要素が取り出され、2 つの変数に取り込まれます。

   SET colorlist=$LISTBUILD("red","blue","green","white")
   SET $LISTGET(a,b)=colorlist
   WRITE "a=",a," b=",b   /* a="red" b="blue" */

以下の例では、SET $LISTGET によって、リストから要素が取り出され、5 つの変数に取り込まれます。指定された list には 5 つ目の要素がないため、対応する var 変数 (e) は NULL 文字列 ("") の値で定義されます。

   SET (a,b,c,d,e)=0
   SET colorlist=$LISTBUILD("red","blue","green","white")
   SET $LISTGET(a,b,c,d,e)=colorlist
   WRITE "a=",a," b=",b," c=",c," d=",d," e=",e
   /* a="red" b="blue" c="green" d="white" e= */

以下の例では、SET $LISTGET によって、リストから要素が取り出され、4 つの変数に取り込まれます。指定された list には 3 つ目の要素がないため、対応する var 変数 (c) は NULL 文字列 ("") の値で定義されます。

   SET (a,b,c,d)=0
   SET colorlist=$LISTBUILD("red","blue",,"white")
   SET $LISTGET(a,b,c,d)=colorlist
   WRITE "a=",a," b=",b," c=",c," d=",d
   /* a="red" b="blue" c= d="white" */

以下の例では、SET $LISTGET によって、リストから要素が取り出され、4 つの変数に取り込まれます。list の 3 つ目の要素は入れ子になったリストであるため、対応する var 変数 (c) にはリスト値が含まれます。

   SET (a,b,c,d)=0
   SET colorlist=$LISTBUILD("red","blue",$LISTBUILD("green","yellow"),"white")
   SET $LISTGET(a,b,c,d)=colorlist
   WRITE "a=",a," b=",b," c=",c," d=",d
   /* a="red" b="blue" c=$LB("green","yellow") d="white" */

例

以下の例の $LISTGET 関数は、position で指定されたリスト要素の値を返します (position の既定は 1 です)。

   SET list=$LISTBUILD("A","B","C")
   WRITE !,$LISTGET(list)     ; returns "A"
   WRITE !,$LISTGET(list,1)   ; returns "A"
   WRITE !,$LISTGET(list,3)   ; returns "C"
   WRITE !,$LISTGET(list,*)   ; returns "C"
   WRITE !,$LISTGET(list,*-1) ; returns "B"

以下の例の $LISTGET 関数は、リストの未定義の 2 つ目の要素が見つかった場合に、値を返します。最初の 2 つは、ユーザが default 値として定義した疑問符 (?) を返します。その後の 2 つは、ユーザが default 値を指定していないため、NULL 文字列を返します。

   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2,"?"),!
   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1,"?"),!
   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2),!
   WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1)

以下の例は、リスト内のすべての要素の値を返します。この例は、リストの末尾の前後の位置も列挙します。値が存在しない場合は、default 値が返されます。

   SET list=$LISTBUILD("a","b",,"d",,,"g")
   SET llen=$LISTLENGTH(list)
      FOR x=0:1:llen+1 { 
      WRITE "position ",x,"=",$LISTGET(list,x," no value"),!
      }
      WRITE "end of the list"

以下の例は、リスト内のすべての要素の値を逆の順序で返します。値が省略されると、default 値が返されます。

   SET list=$LISTBUILD("a","b",,"d",,,"g")
   SET llen=$LISTLENGTH(list)
      FOR x=0:1:llen { 
      WRITE "position *-",x,"=",$LISTGET(list,*-x," no value"),!
      }
      WRITE "beginning of the list"

以下の例の $LISTGET 関数は、NULL 文字列の list 要素値を返します。これらの関数は、default 値を返しません。

   WRITE "returns:",$LISTGET($LB(""),1,"no value"),!
   WRITE "returns:",$LISTGET($LB(""),*,"no value"),!
   WRITE "returns:",$LISTGET($LB(""),*-0,"no value")

以下の例の $LISTGET 関数は、すべて default 値を返します。

   WRITE $LISTGET("",1,"no value"),!
   WRITE $LISTGET($LB(),1,"no value"),!
   WRITE $LISTGET($LB(UndefinedVar),1,"no value"),!
   WRITE $LISTGET($LB(,),1,"no value"),!
   WRITE $LISTGET($LB(,),*,"no value"),!
   WRITE $LISTGET($LB(,),*-1,"no value"),!
   WRITE $LISTGET($LB(""),2,"no value"),!
   WRITE $LISTGET($LB(""),*-1,"no value")