$LISTBUILD (ObjectScript)
構文
$LISTBUILD(element,...)
$LB(element,...)
SET $LISTBUILD(var1,var2,...)=list
SET $LB(var1,var2,...)=list
引数
引数 | 説明 |
---|---|
element | リスト要素値を指定する式です。単一の式、またはコンマ区切りの式リスト内の式を指定できます。省略された要素に対して、プレースホルダとしてのコンマを指定できます。 |
var | 単一の変数、またはコンマ区切りの変数リスト内の変数を指定できます。省略された変数に対して、プレースホルダとしてのコンマを指定できます。var には、ローカル、プロセス・プライベート、グローバル、添え字なし、添え字付きなどの種類の変数を指定できます。 |
list | 有効なリストとして評価される式。リストにはエンコードが含まれるので、list は $LISTBUILD または $LISTFROMSTRING を使用して作成されるか、あるいは $LIST を使用して別のリストから抽出されなければなりません。 |
概要
$LISTBUILD には、$LISTBUILD と SET $LISTBUILD の 2 つの構文形式があります。
-
$LISTBUILD(element1,element2,...) は 1 つ以上の式を取り、1 つの式に対して 1 つの要素を持つエンコードされたリスト構造を返します。要素は、指定された順序でリスト内に配置されます。要素は 1 からカウントされます。
-
SET $LISTBUILD(var1,var2,...)=list は、リストから複数の要素を取り出して、変数に取り込みます。これは、SET $LISTGET(var1,var2,...)=list に類似しています。これらは、明示的な値が割り当てられていない変数の処理方法において違いがあります。SET $LISTGET は、そういった変数を定義して (これにより <UNDEFINED> エラーが回避されます)、空の文字列 (NULL 値、前の値があれば上書き) を割り当てます。SET $LISTBUILD はそういった変数を定義することはありません。変数に前の値がない場合は <UNDEFINED> エラーが生成され、変数に前の値がある場合はその値が保持されます。
$LISTBUILD(element1,element2,...)
リストの作成には、以下の関数を使用できます。
-
$LISTBUILD は、複数のデータ項目 (文字列または数値) から、データ項目ごとに 1 つのリスト要素を含むリストを作成します。$LISTBUILD を使用して、データを含まないリスト要素を作成することもできます。
-
$LISTFROMSTRING は、複数の区切られた要素を持つ 1 つの文字列からリストを作成します。
-
$LIST は、既存のリストからサブリストを抽出します。
-
NULL 文字列 ("") も、有効なリストと見なされます。NULL リスト (要素を含まないリスト) を表すには NULL 文字列 ("") を使用します。$LISTLENGTH("") は、リスト要素を含まないため、0 の要素数を返します。
-
$CHAR の特定の出力不能文字の組み合わせ ($CHAR(1)、$CHAR(2,1)、$CHAR(3,1,asciicode) など) により、エンコードされた空のリストまたは 1 要素のリストを返すこともできます。
$LISTVALID 関数を使用すると、式が有効なリストであるかどうかを判定できます。
$LISTBUILD は、$LISTDATA、$LISTFIND、$LISTGET、$LISTNEXT、$LISTLENGTH、$LISTSAME、$LISTTOSTRING などの他の $LIST 関数と共に使用します。
リスト要素の 1 つ、または複数の文字がワイド (Unicode) 文字の場合、その式のすべての文字がワイド文字として表されます。複数のシステムにまたがる互換性を保証するために、$LISTBUILD はハードウェア・プラットフォームに関係なく、これらのバイトを常に同じ方法で格納します。ワイド文字はバイト文字列として記述されます。
$LISTBUILD とその他の $LIST 関数は、最適化された 2 進数の表現を使用してデータ要素を格納します。このため、エンコードされたリストを比較するときに、予期されているような等価テストが利用できない場合もあります。他のコンテキストでは同等と見なされるデータに、異なる内部表現がある場合もあります。例えば、$LISTBUILD(1) は $LISTBUILD(“1”) と等しくなく、$LISTBUILD(1.0) は $LISTBUILD(1) と等しくありません。しかし、$LIST および $LISTTOSTRING などのリスト表示関数は、キャノニック形式で数値リスト要素値を返します。そのため、$LIST($LISTBUILD(1),1)=$LIST($LISTBUILD("1"),1) となります。
同じ理由から、$LISTBUILD によって返されたエンコードされたリスト値は、$PIECE や 2 つの引数形式の $LENGTH など、区切り文字を使用する文字検索や関数の解析には使用するべきではありません。$LISTBUILD で生成されたリストの要素は、区切り文字によってマークされないので、任意の文字を含むことができます。
SET $LISTBUILD
SET コマンドの等号の左側で使用された場合、$LISTBUILD 関数は、単一の処理でリストから複数の要素を取り出します。構文は、以下のとおりです。
SET $LISTBUILD(var1,var2,...)=list
SET $LISTBUILD の var 引数は、コンマで区切られた変数のリストです。これらの変数はそれぞれ、対応する位置にある list 要素の値に設定されます。したがって、var1 は、最初の list 要素の値に設定され、var2 は 2 つ目の list 要素の値に設定されるというようになります。var 引数が既存の変数である必要はありません。変数は、SET $LISTBUILD によって値に割り当てられるときに、定義されます。
-
var 引数の数は、list 要素の数より少なくても、多くてもかまいません。未指定の var 値では、前の値が保持されます。前に値が定義されていない場合は、未定義のままです。この動作を SET $LISTGET と比較してください。余分な list 要素は無視されます。
-
var 引数と list 要素のいずれかまたは両方に、プレースホルダのコンマで表された、省略された値を含めることができます。省略された var 引数は未定義です。list 要素を省略すると、対応する var 値で前の値が維持されます。前に値が定義されていない場合は、未定義のままです。この動作を SET $LISTGET と比較してください。
SET $LISTBUILD はアトミック処理です。コンパイル済みのプログラムでの var 引数の最大数は 1024 個です。ターミナルから実行した場合の var 引数の最大数は 128 個です。これらの制限を超過しようとすると、<SYNTAX> エラーが発行されます。
var 引数がオブジェクト・プロパティ (object.property) である場合、プロパティは多次元でなければなりません。すべてのプロパティは、オブジェクト・メソッド内で i%property インスタンス変数として参照できます。
以下の例では、(等号の右側にある) $LISTBUILD によって、4 つの要素を使用してリストが作成されます。
以下の例では、SET $LISTBUILD によって、リストから最初の 2 つの要素が取り出され、2 つの変数に取り込まれます。
SET colorlist=$LISTBUILD("red","blue","green","white")
SET $LISTBUILD(a,b)=colorlist
WRITE "a=",a," b=",b /* a="red" b="blue" */
以下の例では、SET $LISTBUILD によって、リストから要素が取り出され、5 つの変数に取り込まれます。指定された list には 5 つ目の要素がないため、対応する var 変数 (e) には、その前の値が含まれます。
SET (a,b,c,d,e)=0
SET colorlist=$LISTBUILD("red","blue","green","white")
SET $LISTBUILD(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=0 */
以下の例では、SET $LISTBUILD によって、リストから要素が取り出され、4 つの変数に取り込まれます。指定された list には 3 つ目の要素がないため、対応する var 変数 (c) には、その前の値が含まれます。
SET (a,b,c,d)=0
SET colorlist=$LISTBUILD("red","blue",,"white")
SET $LISTBUILD(a,b,c,d)=colorlist
WRITE "a=",a," b=",b," c=",c," d=",d
/* a="red" b="blue" c=0 d="white" */
以下の例では、SET $LISTBUILD によって、リストから要素が取り出され、4 つの変数に取り込まれます。list の 3 つ目の要素は入れ子になったリストであるため、対応する var 変数 (c) にはリスト値が含まれます。
SET (a,b,c,d)=0
SET colorlist=$LISTBUILD("red","blue",$LISTBUILD("green","yellow"),"white")
SET $LISTBUILD(a,b,c,d)=colorlist
WRITE "a=",a," b=",b," c=",c," d=",d
/* a="red" b="blue" c=$LB("green","yellow") d="white" */
例
ここに示す例の多くでは、$LISTTOSTRING 関数を使用して、表示のために $LISTBUILD 返り値に変換します。$LISTBUILD は直接表示できないエンコードされた文字列を返します。
以下の例は、3つの要素を持つリスト "Red,Blue,Green" を作成します。
SET colorlist=$LISTBUILD("Red","Blue","Green")
WRITE $LISTTOSTRING(colorlist,"^")
以下の例では、"3^0^44^5.6^33^400" と表示される 6 つの数値要素のリストを作成します。$LISTBUILD は、キャノニック形式と同じでない場合がある、最適化された 2 進数表記に基づいて、数値要素値をエンコードします。$LIST および $LISTTOSTRING などのリスト表示関数は、キャノニック形式で数値要素値を返します。
SET numlist=$LISTBUILD(003,0.00,44.0000000,5.6,+33,4E2)
WRITE $LISTTOSTRING(numlist,"^")
要素の省略
要素式を省略すると、エンコードされた要素が定義されますが、その要素のデータ値は定義されません。
以下の例では、$LISTBUILD 文はどちらも、2 つ目の要素に未定義の値がある、有効な 3 要素のリストを作成します。要素を省略することと、要素に未定義の変数を指定することで、生じる結果はまったく同じです。$LISTBUILD は、未定義の変数をリスト要素として取ることができ、これによってエラーが生成されることはありません。また、結果のリストは $LISTVALID のテストに合格します。しかし、この未定義のリスト要素を $LIST や $LISTTOSTRING などのリスト関数で参照すると、<NULL VALUE> エラーが生成されます。
KILL a
SET list1=$LISTBUILD("Red",,"Green")
SET list2=$LISTBUILD("Red",a,"Green")
WRITE "List lengths:",$LISTLENGTH(list1)," ",$LISTLENGTH(list2),!
IF $LISTVALID(list1)=1,$LISTVALID(list2)=1 {
WRITE "These are valid lists",! }
IF list1=list2 {WRITE "and they're identical"}
ELSE {WRITE "They're not identical"}
以下の例は、未定義の要素を、リスト内だけでなく、リストの末尾にも指定できることを示しています。末尾に未定義の要素があるリストは、有効なリストです。しかし、この未定義の要素をリスト関数で参照すると、<NULL VALUE> エラーが生成されます。
KILL z
SET list3=$LISTBUILD("Red",)
SET list4=$LISTBUILD("Red",z)
WRITE "List lengths:",$LISTLENGTH(list3)," ",$LISTLENGTH(list4),!
IF $LISTVALID(list3)=1,$LISTVALID(list4)=1 {
WRITE "These are valid lists",! }
IF list3=list4 {WRITE "and they're identical"}
ELSE {WRITE "They're not identical"}
しかし、以下の例では、2 つ目の要素にデータ値 (空の文字列) を持つ 3 つの要素のリストを生成します。2 つ目の要素を参照する際に、エラーは発生しません。
SET list5=$LISTBUILD("Red","","Green")
SET list5len=$LISTLENGTH(list5)
WRITE "List length: ",list5len,!
FOR i=1:1:list5len {
WRITE "Element ",i," value: ",$LIST(list5,i),! }
データを含まないリストまたは NULL 文字列データを含むリスト
$LISTBUILD を使用して作成されたリストには、少なくとも 1 つのエンコードされたリスト要素が含まれます。その要素には、データが含まれる場合と含まれない場合があります。$LISTLENGTH はデータではなく要素をカウントするため、$LISTBUILD を使用して作成されたリストのリスト長さは 1 以上になります。
データ値が未定義である $LISTBUILD 要素を参照すると、<NULL VALUE> エラーが生成されます。以下は、すべて “空” のリストを作成する有効な $LISTBUILD 文です。しかし、前述のリストのような要素を参照しようとすると、<NULL VALUE> エラーになります。
TRY {
SET x=$LISTBUILD(UndefinedVar)
SET y=$LISTBUILD(,)
SET z=$LISTBUILD()
IF $LISTVALID(x)=1,$LISTVALID(y)=1,$LISTVALID(z)=1 {
WRITE "These are valid lists",! }
WRITE "$LB(UndefinedVar) contains ",$LISTLENGTH(x)," elements",!
WRITE "$LB(,) contains ",$LISTLENGTH(y)," elements",!
WRITE "$LB() contains ",$LISTLENGTH(z)," elements",!
/* Attempt to use null lists */
WRITE "$LB(UndefinedVar) list value ",$LISTTOSTRING(x,"^"),!
WRITE "$LB(,) list value ",$LISTTOSTRING(y,"^"),!
WRITE "$LB() list value ",$LISTTOSTRING(z,"^"),!
}
CATCH exp { WRITE !!,"In the CATCH block",!
IF 1=exp.%IsA("%Exception.SystemException") {
WRITE "System exception",!
WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
WRITE "Location: ",exp.Location,!
WRITE "Code: "
}
ELSE { WRITE "Some other type of exception",! RETURN }
WRITE exp.Code,!
WRITE "Data: ",exp.Data,!
RETURN
}
データに NULL 文字列値が含まれていますが、以下は、データを含むリスト要素を作成する有効な $LISTBUILD 文です。
SET x=$LISTBUILD("")
WRITE "list contains ",$LISTLENGTH(x)," elements",!
WRITE "list value is ",$LISTTOSTRING(x,"^"),!
SET y=$LISTBUILD($CHAR(0))
WRITE "list contains ",$LISTLENGTH(y)," elements",!
WRITE "list value is ",$LISTTOSTRING(y,"^")
リストの入れ子
リストの要素自体がリストである場合もあります。例えば、以下の文は 3 つ目の要素が "Walnut,Pecan" という 2 つの要素を持つリストである、3 つの要素を持つリストを作成します。
SET nlist=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan"))
WRITE "Nested list length is ",$LISTLENGTH($LIST(nlist,3)),!
WRITE "Full list length is ",$LISTLENGTH(nlist),!
WRITE "List is ",$LISTTOSTRING(nlist,"^"),!
リストの連結
連結演算子 (_) を使用して 2 つのリストを連結すると、その 2 つのリストを結合した別のリストが生成されます。
以下の例では、2 つのリストを連結することで、LISTBUILD を使用して作成したのと同じ要素を持つ同一のリストを作成します。
SET list1=$LISTBUILD("A","B")
SET list2=$LISTBUILD("C","D","E")
SET clist=list1_list2
SET list=$LISTBUILD("A","B","C","D","E")
IF clist=list {WRITE "they're identical",!}
ELSE {WRITE "they're not identical",!}
WRITE "concatenated ",$LISTTOSTRING(clist,"^"),!
WRITE "same list as ",$LISTTOSTRING(list,"^")
文字列をリストに連結することはできません。そのようにすると、結果に最初にアクセスしようとしたときに、<LIST> エラーが生成されます。
TRY {
SET list=$LISTBUILD("A","B")_"C"
WRITE "$LISTBUILD completed without error",!
SET listlen=$LISTLENGTH(list)
WRITE "$LISTLENGTH completed without error",!
SET listval=$LISTTOSTRING(list,"^")
WRITE "$LISTTOSTRING completed without error",!
}
CATCH exp { WRITE !!,"In the CATCH block",!
IF 1=exp.%IsA("%Exception.SystemException") {
WRITE "System exception",!
WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
WRITE "Location: ",exp.Location,!
WRITE "Code: "
}
ELSE { WRITE "Some other type of exception",! RETURN }
WRITE exp.Code,!
WRITE "Data: ",exp.Data,!
RETURN
}
連結の詳細は、"文字列連結 (_)" を参照してください。
関連項目
-
SET コマンド
-
ZZDUMP コマンド
-
$LIST 関数
-
$LISTDATA 関数
-
$LISTFIND 関数
-
$LISTGET 関数
-
$LISTLENGTH 関数
-
$LISTSAME 関数
-
$LISTUPDATE 関数
-
$LISTVALID 関数