$LISTBUILD

指定した式から要素のリストを作成します。

Synopsis

$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 は、1 つのリストから複数の要素を変数に抽出します。list の各要素が、$LISTBUILD パラメータ・リスト内でのその要素の位置に対応する var 変数にコピーされます。

$LISTBUILD(element1,element2,...)

$LISTBUILD は 1 つ以上の式を取り、1 つの式に対して 1 つの要素を持つエンコードされたリスト構造を返します。要素は、指定された順序でリスト内に配置されます。要素は 1 からカウントされます。

リストの作成には、以下の関数を使用できます。

$LISTBUILD は、複数のデータ項目 (文字列または数値) から、データ項目ごとに 1 つのリスト要素を含むリストを作成します。$LISTBUILD を使用して、データを含まないリスト要素を作成することもできます。
$LISTFROMSTRING は、複数の区切られた要素を持つ 1 つの文字列からリストを作成します。
$LIST は、既存のリストからサブリストを抽出します。
NULL 文字列 ("") も、有効なリストと見なされます。NULL リスト (要素を含まないリスト) を表すには NULL 文字列 ("") を使用します。$LISTLENGTH("") は、リスト要素を含まないため、0 の要素数を返します。

$LISTVALID 関数を使用すると、式が有効なリストであるかどうかを判定できます。

$LISTBUILD は、$LISTDATA、$LISTFIND、$LISTGET、$LISTNEXT、$LISTLENGTH、$LISTSAME、$LISTTOSTRING などの他の $LIST 関数と共に使用します。

リスト要素の 1 つ、または複数の文字がワイド (Unicode) 文字の場合、その式のすべての文字がワイド文字として表されます。複数のシステムにまたがる互換性を保証するために、$LISTBUILD はハードウェア・プラットフォームに関係なく、これらのバイトを常に同じ方法で格納します。ワイド文字はバイト文字列として記述されます。

Note:

$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

$LISTBUILD の var 引数は、コンマで区切られた変数のリストです。これらの変数はそれぞれ、$LISTBUILD パラメータ・リストでのその位置に対応する list の要素を受け取ります。var 引数は既存の変数である必要はありません。この変数は SET $LISTBUILD が値を割り当てたときに定義されます。

var 引数の数は、list 要素の数より少なくても多くてもかまいません。未指定の var 値では、前の値が維持されます。前の値が定義されていない場合は、未定義のままです。余分な list 要素は無視されます。
var 引数と list 要素のいずれかまたは両方に、プレースホルダとしてコンマで表される省略値を含めることができます。省略された var 引数は未定義となります。list 要素を省略すると、対応する var 値で前の値が維持されます。前の値が定義されていない場合は、未定義のままです。

SET $LISTBUILD はアトミック処理です。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 つの変数に抽出されます。3 つ目の list 要素の値は入れ子のリストであるため、対応する 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 要素のリストを作成します。要素を省略することと、要素に未定義の変数を指定することで、生じる結果はまったく同じです。どちらの場合でも、リスト関数 ($LIST または $LISTTOSTRING など) で 2 番目の要素を参照すると、<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(NULL)
     SET y=$LISTBUILD(,)
     SET z=$LISTBUILD()
     IF $LISTVALID(x)=1,$LISTVALID(y)=1,$LISTVALID(z)=1 {
        WRITE "These are valid lists",! }
     WRITE "$LB(NULL) contains ",$LISTLENGTH(x)," elements",!
     WRITE "$LB(,) contains ",$LISTLENGTH(y)," elements",!
     WRITE "$LB() contains ",$LISTLENGTH(z)," elements",!
     /* Attempt to use null lists */
     WRITE "$LB(NULL) 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
   }

連結の詳細は、"Caché ObjectScript の使用法" の "演算子" の章を参照してください。