$LISTGET
Synopsis
$LISTGET(list,position,default) $LG(list,position,default)
パラメータ
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 パラメータを指定する必要があります。 |
概要
$LISTGET は、指定したリストの要求した要素を返します。position の値が、存在しない要素を参照する場合や、値が未定義の要素を指定する場合は、default の値が返されます。
$LISTGET 関数は、$LIST 関数の 1-引数形式および 2-引数形式とまったく同じですが、$LIST が <NULL VALUE> エラーを発生する条件下では、$LISTGET は既定値を返します。<NULL VALUE> エラーが発生する条件に関する詳細は、"$LIST" 関数の説明を参照してください。
パラメータ
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)、Caché は <RANGE> エラーを発行します。
-
position が 0 または -0 の場合、$LISTGET は default の値を返します。
position パラメータの数値部分は整数に評価されます。Caché は、小数を切り捨てて、その整数部分のみにします。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 番目の要素より前の場合は、Caché は <RANGE> エラーを発行します。
default パラメータを省略すると、既定値として NULL 文字列 ("") が返されます。
例
以下の例の $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(NULL),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")
関連項目
-
$LIST 関数
-
$LISTBUILD 関数
-
$LISTDATA 関数
-
$LISTFIND 関数
-
$LISTLENGTH 関数
-
$LISTSAME 関数
-
$LISTUPDATE 関数
-
$LISTVALID 関数