$LIST

リスト要素を返す方法

$LIST は、リスト要素を返します。返される要素は、使用するパラメータによって決まります。

• $LIST(list) は、リストの最初の要素を文字列として返します。

• $LIST(list,position) は、position で指定した要素をテキスト文字列として返します。

• $LIST(list,position,end) は、指定された開始 position から指定された end 位置 (この位置を含む) までの範囲の、リストの要素を格納している “sublist” (エンコードされたリスト文字列) を返します。position と end が同じ要素を指定している場合、$LIST は、この要素をエンコードされたリストとして返します。

list

1 つ以上の要素を含む、エンコードされたリスト文字列。リストは、$LISTBUILD または $LISTFROMSTRING を使用して作成するか、$LIST 関数を使用して、他のリストから抽出することができます。

要素を返す場合、list は変数またはオブジェクト・プロパティにすることができます。

要素を置換するために、等号の左側で SET と共に $LIST を使用する場合、list は変数または多次元プロパティ参照にすることができますが、非多次元オブジェクト・プロパティにすることはできません。

有効な list 引数は以下のとおりです。

   SET myList = $LISTBUILD("Red","Blue","Green","Yellow")
   WRITE !,$LIST(myList,2)   ; prints Blue
   SET subList = $LIST(myList,2,4)
   WRITE !,$LIST(subList,2)  ; prints Green

以下の例では、subList は有効な list 引数ではありません。ここでは、subList は通常の文字列として返された 1 つの要素であり、エンコードされたリスト文字列ではないからです。

   SET myList = $LISTBUILD("Red","Blue","Green","Yellow")
   SET subList = $LIST(myList,2)
   WRITE $LIST(subList,1)

SET $LIST 構文形式では、list を非多次元オブジェクト・プロパティにすることはできません。

position

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

• position が正の整数の場合、$LIST は list の先頭から要素をカウントします。position が list 内の要素数よりも大きい場合、Caché は <NULL VALUE> エラーを発行します。

• position が * (アスタリスク) の場合、$LIST は list 内の最後の要素を返します。

• position が *-n (アスタリスクとそれに続く負の数) の場合、$LIST は list の末尾からオフセット分だけ逆向きに要素をカウントします。したがって、*-0 はリスト内の最後の要素であり、*-1 は最後から 2 番目のリスト要素 (末尾からのオフセットが 1) です。position の相対オフセット・カウントが list 内の要素数と等しい (結果的に、0 番目の要素を指定している) 場合、Caché は <NULL VALUE> エラーを発行します。position の相対オフセット・カウントが list 内の要素数よりも大きい場合、Caché は <RANGE> エラーを発行します。

• SET $LIST 構文のみ — position が *+n (アスタリスクとそれに続く正の整数) の場合、SET $LIST は list の末尾のオフセット分先の位置に要素を追加します。つまり、*+1 の場合は list の末尾の先に 1 つの要素が追加され、*+2 の場合は list の末尾の 2 つ先の位置に 1 つの要素が追加されます (末尾と追加位置の間にはNULL 文字列の要素が埋め込まれます)。

• position が 0 または -0 の場合、Caché は <NULL VALUE> エラーを発行します。

end パラメータが指定されている場合、position は要素の範囲の最初の要素を指定します。要素の範囲は、常にエンコードされたリスト文字列として返されます。(position と end が同じ値のとき) 要素が 1 つだけ返されますが、その値はエンコードされた文字列として返されます。つまり、$LIST(x,2) は同じ要素ですが、 $LIST(x,2,2) と同じデータ値にはなりません。

end

整数で指定される、要素範囲の最後の要素の位置。end を指定するには、position を指定する必要があります。end が小数の場合、整数部に切り捨てられます。

end が指定されている場合、返される値はエンコードされたリスト文字列です。このような文字列はエンコードされているため、他の $LIST 関数によってのみ処理される必要があります。

• position < end ： end と position が正の整数であり、position < end である場合、$LIST は、指定した要素のリストを含むエンコードされたサブリストを返します (position および end の要素を含む)。position が 0 または 1 の場合、サブリストの先頭は list 内の最初の要素になります。end が list 内の要素数よりも大きい場合、$LIST は position からリストの末尾までのすべての要素を格納しているエンコードされたサブリストを返します。end が *-n の場合、position は正の整数か、この end 位置以上の *-n になります。つまり、$LIST(fourlist,*-1,*)、$LIST(fourlist,*-3,*-2)、$LIST(fourlist,2,*-1) は、すべて有効なサブリストになります。

• position = end ： end および position が同じ要素に評価される場合、$LIST は、その 1 つの要素を含むエンコードされたサブリストを返します。例えば、4 要素のリストでは、end と position が同じになる可能性も ($LIST(fourlist,2,2)、$LIST(fourlist,*,*)、または $LIST(fourlist,*-2,*-2))、同じ要素を指定する可能性も ($LIST(fourlist,4,*), $LIST(fourlist,3,*-1)) あります。

• position > end ： position > end の場合、$LIST は NULL 文字列 ("") を返します。例えば、4 要素のリストでは、$LIST(fourlist,3,2)、$LIST(fourlist,7,*)、または $LIST(fourlist,*-1,*-2) は、どれも NULL 文字列を返します。

• position=0、end ：end が指定されていて、position がゼロ (0) または位置 0 に評価される負のオフセットの場合、position 0 は 1 と等しくなります。したがって、end がゼロより大きい要素の位置に評価される場合、$LIST は、position 1 から end 位置までの要素を含むエンコードされたサブリストを返します。end が要素位置 0 に評価される場合も、position > end となるため、$LIST は NULL 文字列 ("") を返します。

• SET $LIST 構文のみ — end が *+n (アスタリスクとそれに続く正の整数) の場合、SET $LIST は list の末尾のオフセット分先の位置に要素の範囲を追加します。position が *+n の場合、SET $LIST は値の範囲を追加します。position が正の整数または *-n の場合、SET $LIST は値の置換と追加の両方を行います。最後の要素を置換して要素を追加するには、SET $LIST(mylist,*+0,*+n) を指定します。指定した範囲の開始位置が list の末尾を超える場合、リストには NULL 文字列の要素が必要な分だけ埋め込まれます。end が指定の値の範囲よりも大きい場合、末尾の埋め込みは実行されません。

非推奨の -1 の値

古いコードでは、-1 の position または end の値は、リスト内の最後の要素を表します。-1 の値は、*、*+n、または *-n の構文と組み合わせて使用することはできません。

*-n および *+n パラメータ値の指定

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

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

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

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

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

  SET count=2
  SET alph=$LISTBUILD("a","b","c","d")
  SET $LIST(alph,*+count)="F"
  WRITE $LISTTOSTRING(alph,"^",1)

これらのパラメータ値内では、空白を使用できます。

2 パラメータ操作

以下の 2 パラメータ操作を実行できます。2 パラメータ操作では、要素の値を文字列として指定します。リストとして要素の値を指定すると、リスト内にサブリストが作成されます。

• 要素の値を新しい値に置き換える

    SET $LIST(fruit,2)="orange"   ; count from beginning of list
    SET $LIST(fruit,*)="pear"     ; element at end of list
    SET $LIST(fruit,*-2)="peach"  ; offset from end of list
  

  

• 要素の値を削除する (ここでは値を NULL 文字列に設定しています。要素の位置は削除していません)

    SET $LIST(fruit,2)=""

  

• 要素をリストに追加する。*+n 構文を使用すると、リストの末尾への追加も、リストの末尾より先の位置への追加も可能です。SET $LIST は、必要に応じて NULL 値の要素を挿入して指定した位置までの間を埋め込みます。

    SET $LIST(fruit,*+1)="plum"

  

• 1 つの要素を要素のサブリストに置き換える

    SET $LIST(fruit,3)=$LISTBUILD("orange","banana")

  

3 パラメータ操作

以下の 3 パラメータ (範囲) 操作を実行できます。範囲操作では、要素の値を 1 つだけ指定する場合でも、その値をリストとして指定する点に注意してください。

• 1 つの要素を複数の要素に置き換える

    SET $LIST(fruit,3,3)=$LISTBUILD("orange","banana")

  

• 要素の値の範囲を新しい値の同じ数に置き換える

    SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")

  

• 要素の値の範囲を大きな新しい値または小さな新しい値に置き換える

    SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach")

  

• 要素の値の範囲を削除する (ここでは要素の値を NULL 文字列に設定しています。要素の位置は削除していません)

    SET $LIST(fruit,2,3)=$LISTBUILD("","")

  

• 要素の値の範囲と、それらの位置を削除する

    SET $LIST(fruit,2,3)=""

  

• 要素の範囲をリストに追加する。*+n 構文を使用すると、リストの末尾への追加も、リストの末尾より先の位置への追加も可能です。SET $LIST は、必要に応じて NULL 値の要素を挿入して指定した位置までの間を埋め込みます。

    SET $LIST(fruit,*+1,*+2)=$LISTBUILD("plum","pear")

  

  SET $LIST は、指定した要素の値のみを追加します。end の位置が指定の要素数よりも大きい場合、末尾の空の要素の位置は作成されません。

$LIST を使用して要素を返す例

以下の例は、$LIST の 2 パラメータ形式を使用して、リスト要素を文字列として返します。

以下の 2 つの $LIST 文はリストの先頭要素である “Red” を返します。最初の文は、既定で先頭要素を返します。2 番目の文は、position パラメータが 1 に設定されているために先頭要素を返します。値は、文字列として返されます。

   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LIST(colorlist),!
   WRITE $LIST(colorlist,1)

以下の 2 つの $LIST 文はリストの 2 番目の要素である “Orange” を返します。最初の文はリストの先頭からカウントします。2 番目の文はリストの末尾から逆向きにカウントします。値は、文字列として返されます。

   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LIST(colorlist,2),!
   WRITE $LIST(colorlist,*-4)

以下の例は、$LIST の 3 パラメータ形式を使用して、1 つ以上の要素をエンコードされたリスト文字列として返します。リストには出力不能なエンコード文字が含まれているため、$LISTTOSTRING を使用して、サブリストを出力可能な文字列に変換する必要があります。

以下の 2 つの $LIST 文は、エンコードされたリスト文字列として、リストの 5 番目の要素である “Blue” を返します。最初の文はリストの先頭からカウントします。2 番目の文はリストの末尾から逆向きにカウントします。範囲として要素が指定されているため、これは 1 つの要素で構成されたリストとして取得されます。

   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LISTTOSTRING($LIST(colorlist,5,5))
   WRITE $LISTTOSTRING($LIST(colorlist,*-1,*-1))

以下の例は “Red Orange Yellow” を返します。これは、リスト内の先頭要素から始まり 3 番目の要素で終了する 3 つの要素のリスト文字列です。

   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LISTTOSTRING($LIST(colorlist,1,3))

以下の例は “Green Blue Violet” を返します。これは、リスト内の 4 番目の要素から始まり最後の要素で終了する 3 つの要素のリスト文字列です。

   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LISTTOSTRING($LIST(colorlist,4,*))

以下の例は、プロパティからのリスト要素を返します。

  SET cfg=##class(%iKnow.Configuration).%New("Trilingual",1,$LB("en","fr","es"))
  WRITE $LIST(cfg.Languages,2)

SET $LIST を使用して要素を置換、削除または追加する例

以下の例は、2 つめの要素を置き換える SET $LIST を示します。

   SET fruit=$LISTBUILD("apple","onion","banana","pear")
   WRITE !,$LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,2)="orange"
   WRITE !,$LISTTOSTRING(fruit,"/")

以下の例は、2 つめと 3 つめの要素を置き換える SET $LIST を示します。

   SET fruit=$LISTBUILD("apple","potato","onion","pear")
   WRITE !,$LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")
   WRITE !,$LISTTOSTRING(fruit,"/")

以下の例は、2 つめと 3 つめの要素を 4 つめの要素に置き換える SET $LIST を示します。

   SET fruit=$LISTBUILD("apple","potato","onion","pear")
   WRITE !,$LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach","tangerine")
   WRITE !,$LISTTOSTRING(fruit,"/")

以下の例では、リストの末尾に 1 つの要素を追加する SET $LIST を示します。

   SET fruit=$LISTBUILD("apple","orange","banana","peach")
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
   SET $LIST(fruit,*+1)="pear"
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)

以下の例では、リストの末尾から 3 つ先に 1 つの要素を追加する SET $LIST を示します。

   SET fruit=$LISTBUILD("apple","orange","banana","peach")
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
   SET $LIST(fruit,*+3)="tangerine"
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)

以下の 4 つの例では、*-n 構文を使用して、リストの末尾からオフセット分の位置の要素を置換する SET $LISTを示します。SET $LIST(x,*-n) と SET $LIST(x,n,*-n) では異なる操作が行われます。SET $LIST(x,*-n) は、指定した要素の value を置換します。SET $LIST(x,n,*-n) は、指定した要素の範囲を削除してから、指定したリストを追加します。

最後から 2 番目の要素を 1 つの値に置き換えるには、SET $LIST(x,*-1) を使用します。

   SET fruit=$LISTBUILD("apple","banana","orange","potato","pear")
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,*-1)="peach"
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")

リストの末尾からオフセット分の位置の 1 つの要素を削除するには、SET $LIST(x,*-n,*-n)="" を使用します。

   SET fruit=$LISTBUILD("apple","banana","orange","potato","pear")
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,*-1,*-1)=""
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")

リストの末尾からオフセット分の位置の 1 つの要素を要素のリストに置き換えるには、SET $LIST(x,*-n,*-n)=list を使用します。

   SET fruit=$LISTBUILD("apple","banana","potato","orange","pear")
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,*-2,*-2)=$LISTBUILD("peach","plum","quince")
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")

リストの末尾からオフセット分の位置の 1 つの要素をサブリストに置き換えるには、SET $LIST(x,*-n)=list を使用します。

   SET fruit=$LISTBUILD("apple","banana","potato","orange","pear")
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,*-2)=$LISTBUILD("peach","plum","quince")
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")

以下の例は、3 つめの要素からリストの最後まで、リストから要素を削除する SET $LIST を示します。

   SET fruit=$LISTBUILD("apple","orange","onion","peanut","potato")
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,3,*)=""
   WRITE !,"list length is ",$LISTLENGTH(fruit)," "
   WRITE $LISTTOSTRING(fruit,"/")

Unicode

リスト要素内に Unicode 文字が 1 つでもあれば、リスト要素全体が Unicode (ワイド) 文字として表されます。リスト内の他の要素は影響されません。

以下の例は、2 つのリストを示しています。y リストは、ASCII 文字のみが含まれる 2 つの要素で構成されます。z リストは 2 つの要素で構成され、最初の要素には Unicode 文字 ($CHAR(960)、つまり pi 記号) が含まれ、2 番目の要素には ASCII 文字のみが含まれます。

   IF $SYSTEM.Version.IsUnicode()  {
   SET y=$LISTBUILD("ABC"_$CHAR(68),"XYZ")
   SET z=$LISTBUILD("ABC"_$CHAR(960),"XYZ")
   WRITE !,"The ASCII list y elements: "
   ZZDUMP $LIST(y,1)
   ZZDUMP $LIST(y,2)
   WRITE !,"The Unicode list z elements: "
   ZZDUMP $LIST(z,1)
   ZZDUMP $LIST(z,2)
   }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}

Caché は、z の先頭要素全体をワイド Unicode 文字でエンコードすることに注意してください。z の 2 番目の要素には Unicode 文字が含まれないため、Caché は 1 バイトの ASCII 文字を使用してエンコードします。

$EXTRACT と $PIECE と比較した $LIST

$LIST は、リストの先頭 (または末尾) から要素 (文字ではありません) をカウントすることで、エンコードされたリストから 1 つの要素を決定します。

$EXTRACT は、文字列の先頭 (または末尾) から文字をカウントすることで、部分文字列を決定します。$EXTRACT は、入力として通常の文字列を取ります。

$PIECE は、文字列内のユーザ定義の区切り文字をカウントすることにより、部分文字列を決定します。$PIECE は、区切り文字として使用するための文字 (または文字列) の複数のインスタンスを含む通常の文字列を入力として取ります。

$LIST は通常の文字列では使用できません。$PIECE および $EXTRACT はエンコードされたリストでは使用できません。