$PIECE

部分文字列を返す方法

string から指定された部分文字列 (piece) を返す場合、返される部分文字列は、使用されるパラメータによって変わります。

• $PIECE(string,delimiter) は、string の先頭の部分文字列を返します。delimiter が string 内に存在する場合は、最初の delimiter の前にある部分文字列です。delimiter が string 内に存在しない場合、返される部分文字列は string です。

• $PIECE(string,delimiter,from) は、位置が from パラメータによって指定される部分文字列を返します。部分文字列は、区切り文字、および string の先頭と末尾によって区切られます。区切り文字自体は返されません。

• $PIECE(string,delimiter,from,to) では、from で指定された部分文字列から、to で指定された部分文字列までの範囲 (from および to で指定された部分を含む) の部分文字列が返されます。この 4 つの引数の $PIECE は、from から to までの部分文字列の間にあり、それらを区切っている delimiter をすべて含んだ部分文字列を返します。to が部分文字列数よりも大きい場合、返される部分文字列には、string の最後までのすべての部分文字列が含まれます。

string

部分文字列を返すために $PIECE を使用する場合、string は、引用符で囲まれた文字列リテラル、キャノニック形式の数値、変数、オブジェクト・プロパティ、または評価結果が文字列または数値になる有効な ObjectScrip 式にできます。ターゲット文字列として NULL 文字列 ("") を指定すると、$PIECE はその他のパラメータ値に関係なく、常に NULL 文字列を返します。

通常、ターゲット文字列には、区切り文字として使用される文字 (または文字列) が含まれます。この文字または文字列は、string 内のデータ値として使用することはできません。

1 つの部分文字列を置換するために、等号の左側で SET と共に $PIECE を使用する場合、string は変数または多次元プロパティ参照にすることができますが、非多次元オブジェクト・プロパティにすることはできません。

delimiter

string 内の部分文字列の区切りとして使用される検索文字列です。引用符で囲まれた文字列リテラル、キャノニック形式の数値、変数、または評価結果が文字列または数値となる有効な ObjectScript 式にできます。

通常、区切り文字には、string 内で決してデータとして使用されることがなく、部分文字列を区切る区切り文字としてのみ使用される特定の文字が指定されます。例えば、delimiter が “^” である場合は、string の値 “Red^Orange^Yellow” には 3 つの区切り部分文字列が含まれます。

区切り文字には、複数文字から成る文字列を指定できますが、それを構成する個々の文字は文字列データ内で使用できます。例えば、delimiter が “^#” である場合は、string の値 “Red^Orange^#^Yellow#Green#^Blue” には、“Red^Orange” と “^Yellow#Green#^Blue” という 2 つの区切り部分文字列が含まれます。

一般に、string の先頭や末尾には delimiter は使用されません。string の先頭や末尾に delimiter が使用されている場合、$PIECE は、その区切り文字を、NULL 文字列 ("") 値を含む部分文字列の境界を示すものとして扱います。例えば、delimiter が “^” である場合は、string の値 “^Red^Orange^Yellow^” には 5 つの区切り部分文字列が含まれており、1 つ目と 5 つ目の部分文字列は NULL 文字列値です。

指定された区切り文字が string に存在しない場合、$PIECE は string 全体を返します。指定された区切り文字が NULL 文字列 ("") である場合、$PIECE は、NULL 文字列を返します。

from

string 内の部分文字列の位置。n (正の整数) を使用して、string の先頭から区切り部分文字列をカウントします。* を使用して、string 内の最後の区切り部分文字列を指定します。*-n を使用して、string 内の最後の区切り部分文字列からオフセット分だけ区切り部分文字列をカウントします。

• 1 は、string の最初の部分文字列を指定します (これは最初の delimiter の前にある部分文字列です)。指定された区切り文字が string にない場合、from 値が 1 であれば string が返されます。from が省略されている場合は、既定値の 1 が使用されます。

• 2 は、string の 2 つ目の部分文字列を指定します (この部分文字列は、1 つ目と 2 つ目の delimiter の間にある部分文字列であるか、1 つ目の delimiter と string の末尾の間にある部分文字列です)。

• * は、string の最後の部分文字列を指定します (これは最後の delimiter の後ろにある部分文字列です)。指定された区切り文字が string にない場合、from 値が * であれば string が返されます。

• *-1 は、string の最後から 2 番目の部分文字列を指定します。*-n は、string の最後の部分文字列からオフセット分だけカウントします。*-0 は string の最後の部分文字列であり、* と *-0 は機能的に同じです。

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

• from が NULL 文字列 ("")、ゼロ、または負数であるか、string 内の部分文字列数よりも大きいカウントまたはオフセットを指定している場合、$PIECE は NULL 文字列を返します。

$PIECE は from の数値をキャノニック形式に変換してから (先頭のプラス記号とマイナス記号を解決して先頭のゼロを削除します)、その数値の小数部分を切り捨てます。

from パラメータが to パラメータと共に使用される場合、from パラメータは文字列として返される部分文字列の範囲の先頭を指定し、to の値よりも小さくなければなりません。

to

from パラメータによって先頭が指定された範囲を終了する、string 内の部分文字列の番号です。返される文字列には、from の位置の文字列と to の位置の文字列に加えて、その両者の間の部分文字列とそれらを区切る区切り文字が含まれます。to パラメータは必ず from と共に使用し、from の値よりも大きい必要があります。

n (正の整数) を使用して、string の先頭から区切り部分文字列をカウントします。* を使用して、string 内の最後の区切り部分文字列を指定します。*-n を使用して、string 内の最後の区切り部分文字列からの逆方向にオフセット分だけ区切り部分文字列をカウントします。

SET $PIECE 構文のみ — *+n (アスタリスクとそれに続く正の整数) が、string の末尾の先に追加する部分文字列の範囲の末尾を指定します。

• from が to よりも小さい場合、$PIECE は、from 位置の部分文字列と to 位置の部分文字列を含む、この範囲内にあるすべての区切られた部分文字列から成る文字列を返します。この返された文字列には、範囲内にある部分文字列と区切り文字が含まれます。to が区切られた部分文字列の数よりも大きい場合、返される文字列には、from 位置の部分文字列から string の末尾までのすべての文字列データ (部分文字列と区切り文字) が含まれます。

• from が to と同じ場合、$PIECE は from の部分文字列を返します。この状況が発生する可能性があるのは、from と to が同じ値であるか、同じ部分文字列を参照する異なる値である場合です。

• from が to より大きい値であるか、ゼロ (0) であるか、または NULL 文字列 ("") である場合は、$PIECE は NULL 文字列を返します。

$PIECE は to の数値をキャノニック形式に変換してから (先頭のプラス記号とマイナス記号を解決して先頭のゼロを削除します)、その数値の小数部分を切り捨てます。

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

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

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

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

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

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

  SET count=2
  SET alph="a^b^c^d"
  SET $PIECE(alph,"^",*+count)="F"
  WRITE alph

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

例 ： 区切り部分文字列を返す方法

以下の例では、それぞれの $PIECE は、"," 区切り文字で識別される指定の部分文字列を返します。

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   WRITE $PIECE(colorlist,","),!     ; returns "Red" (substring 1) by default
   WRITE $PIECE(colorlist,",",3),!   ; returns "Blue" the third substring
   WRITE $PIECE(colorlist,",",*),!   ; returns "Black" the last substring
   WRITE $PIECE(colorlist,",",*-1),! ; returns "Orange" the next-to-last substring

以下の例では、$PIECE は数値の整数部分と小数部分を返します。

   SET int=$PIECE(123.999,".")
   SET frac=$PIECE(123.999,".",*)
   WRITE "integer=",int," fraction =.",frac

以下の例は、colorlist の 3 番目から 5 番目の部分文字列である "Blue,Yellow,Orange" を、"," で区切って返します。

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   SET extract=$PIECE(colorlist,",",3,5)
   WRITE extract

以下の WRITE 文はすべて、最初の部分文字列 "123" を返し、from と to の 値が 1 のとき、これらの形式は同等であることがわかります。

   SET numlist="123#456#789"
   WRITE !,"2-arg=",$PIECE(numlist,"#")
   WRITE !,"3-arg=",$PIECE(numlist,"#",1)
   WRITE !,"4-arg=",$PIECE(numlist,"#",1,1)

以下の例では、string 内に delimiter が使用されていないため、$PIECE 関数は両方とも string 文字列全体を返します。

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   SET extract1=$PIECE(colorlist,"#")
   SET extract2=$PIECE(colorlist,"#",1,4)
   WRITE "#   =",extract1,!,"#,1,4=",extract2

以下の例では、$PIECE はオブジェクト・プロパティの 2 番目の部分文字列を返します。

  SET tStatement = ##class(%SQL.Statement).%New()
  SET tStatement.%SchemaPath="MyTests,Sample,Cinema"
  WRITE "whole schema path: ",tStatement.%SchemaPath,!
  WRITE "2nd piece of schema path: ",$PIECE(tStatement.%SchemaPath,",",2),!

以下の 2 つの例では、より複雑な区切り文字を使用します。

この例は、区切り文字列 "#-#" を使用して、文字列 numlist の 3 つの部分文字列を返します。この場合、区切り文字列を構成する個々の文字の "#" と "-" はデータ値として使用でき、指定された文字シーケンス (#-#) のみが区切り文字列として認識されます。

   SET numlist="1#2-3#-#45##6#-#789"
   WRITE !,$PIECE(numlist,"#-#",1)
   WRITE !,$PIECE(numlist,"#-#",2)
   WRITE !,$PIECE(numlist,"#-#",3)

以下の例では、$CHAR 関数を使用して指定され、連結演算子 (_) を使用して string に挿入されている非 ASCII 区切り文字 (ここでは pi の Unicode 文字) を使用します。

   IF $SYSTEM.Version.IsUnicode()  {
     SET a = $CHAR(960)
     SET colorlist="Red"_a_"Green"_a_"Blue"
     SET extract1=$PIECE(colorlist,a)
     SET extract2=$PIECE(colorlist,a,2)
     SET extract3=$PIECE(colorlist,a,2,3)
     WRITE extract1,!,extract2,!,extract3
     }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}

例 ： 区切り部分文字列を置換する方法

以下の例は、colorlist の値を "Magenta,Green,Cyan,Yellow,Orange,Black" に変更します。

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   WRITE colorlist,!
   SET $PIECE(colorlist,",",1)="Magenta"
   WRITE colorlist,!
   SET $PIECE(colorlist,",",*-3)="Cyan"
   WRITE colorlist,!

置換部分文字列は、元の部分文字列より長くても短くてもかまわず、区切り文字を含んでいてもかまいません。

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   WRITE colorlist,!
   SET $PIECE(colorlist,",",3)="Turquoise,Aqua,Teal"
   WRITE colorlist,!

引数 from と to を指定すると、その範囲に該当する部分文字列が指定の値に置換されます。この例では 4 ～ 6 番目の区切り部分文字列が相当します。

   SET colorlist="Red,Blue,Yellow,Green,Orange,Black"
   WRITE !,colorlist
   SET $PIECE(colorlist,",",4,6)="Yellow+Blue,Yellow+Red"
   WRITE !,colorlist

区切り部分文字列カウントによって (n を使用)、または string の末尾からのオフセットによって (*+n を使用)、1 つ以上の区切り部分文字列を追加できます。SET $PIECE は、指定された位置に区切り部分文字列を追加するために、必要に応じて区切り文字を追加します。以下の例では、どちらも colorlist の値を "Green^Blue^^Red" に変更して、追加の空文字列を区切られた部分文字列に埋め込みます。

   SET colorlist="Green^Blue"
   SET $PIECE(colorlist,"^",4)="Red"
   WRITE colorlist

   SET colorlist="Green^Blue"
   SET $PIECE(colorlist,"^",*+2)="Red"
   WRITE colorlist

string に delimiter が存在しない場合、$PIECE は string を 単一の文字として扱い、前述どおり置換を行います。from 引数を指定していない場合、元の string は新しい値で置き換えられます。

   SET colorlist="Red,Green,Blue"
   WRITE colorlist,!
   SET $PIECE(colorlist,"^")="Purple^Orange"
   WRITE colorlist

delimiter が string に含まれず、from に 1 より大きい整数が指定されている場合、$PIECE は、(from-1) 個の区切り文字を追加して、指定された値を string の末尾に追加します。

   SET colorlist="Red,Green,Blue"
   WRITE colorlist,!
   SET $PIECE(colorlist,"^",3)="Purple"
   WRITE colorlist

from が文字列の先頭より前の位置を指している場合は、Caché は何の処理も実行しません。

   SET colorlist="Red,Green,Blue"
   WRITE colorlist,!
   SET $PIECE(colorlist,",",*-7)="Purple"
   WRITE colorlist

from が文字列の先頭より前の位置を指しており、to が指定されている場合は、Caché は from を位置 1 として扱います。

   SET colorlist="Red,Green,Blue"
   WRITE colorlist,!
   SET $PIECE(colorlist,",",*-7,1)="Purple"
   WRITE colorlist

文字列変数の初期化

string 変数は、値を割り当てる前に定義する必要はありません。以下の例は、newvar を文字パターン ">>>>>>TOTAL" に初期化します。

   SET $PIECE(newvar,">",7)="TOTAL"
   WRITE newvar

詳細は、SET コマンド・ドキュメント" の "$PIECE と $EXTRACT を使用した SET" セクションを参照してください。

区切り文字が NULL 文字列

区切り文字が NULL 文字列の場合、from 引数や to 引数の値に関係なく、元の string が新しい値に置換されます。

以下の 2 つの例では、どちらも colorlist は “Purple” に設定されます。

   SET colorlist="Red,Green,Blue"
   WRITE !,colorlist
   SET $PIECE(colorlist,"")="Purple"
   WRITE !,colorlist

   SET colorlist="Red,Blue,Yellow,Green,Orange,Black"
   WRITE !,colorlist
   SET $PIECE(colorlist,"",3,5)="Purple"
   WRITE !,colorlist

32,768 文字より大きいパラメータを持つ $PIECE

以下の例では、5 個のピリオドと 1 つの NULL を含む文字列を作成します。

   SET x=""
   SET $PIECE(x,".",6)=""
   WRITE x

32767 個のピリオドと 1 つの NULL を含む文字列を作成する、以下の例を考えてください。

   SET x=""
   SET $PIECE(x,".",32768)=""

この例では、実際には文字列の最大長内に収まっていますが、長い文字列が有効になっていない場合は、<MAXSTRING> エラーが発生します。長い文字列は、既定ではシステム全体で有効になっています。32,767 文字を超える長さのパラメータを指定した $PIECE を使用する場合は、Config.MiscellaneousOpens in a new tab クラスの EnableLongStringsOpens in a new tab プロパティを使用して、システム全体に適用される長い文字列の設定を確認または設定できます。

データ値をアンパックする $PIECE の使用法

$PIECE は、通常、区切り文字で区切られた複数のフィールドを含むデータ値を "アンパック" するために使用されます。一般的な区切り文字には、スラッシュ (/)、コンマ (,)、スペース ( )、およびセミコロン (;) が含まれます。以下の例の値は、$PIECE を使用すると効率的に処理できます。

"John Jones/29 River St./Boston MA, 02095"
"Mumps;Measles;Chicken Pox;Diptheria"
"45.23,52.76,89.05,48.27"

$PIECE および $LENGTH

2-引数形式の $LENGTH は、区切り文字に基づいて、文字列の部分文字列数を返します。$LENGTH を使用して、文字列内の部分文字列の数を調べてから、$PIECE を使用して、以下の例で示すように、個々の部分文字列を抽出します。

   SET sentence="The quick brown fox jumped over the lazy dog's back."
   SET delim=" "
   SET countdown=$LENGTH(sentence,delim)
   SET countup=1
   FOR reps=countdown:-1:1 {
      SET extract=$PIECE(sentence,delim,countup)
      WRITE !,countup," ",extract
      SET countup=countup+1
   }
   WRITE !,"All done!"

NULL 値

$PIECE は、値が NULL 文字列の部分文字列と、存在しない部分文字列を区別しません。両方とも、NULL 文字列を返します。例えば、以下の 2 つの例は両方とも、from 値の 7 に対して NULL 文字列値を返します。

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   SET extract1=$PIECE(colorlist,",",6)
   SET extract2=$PIECE(colorlist,",",7)
   WRITE "6=",extract1,!,"7=",extract2

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black,"
   SET extract1=$PIECE(colorlist,",",6)
   SET extract2=$PIECE(colorlist,",",7)
   WRITE "6=",extract1,!,"7=",extract2

最初の例では、7 番目の部分文字列がないので、NULL 文字列が返されます。2 番目の例では、string の最後に区切り文字で示された 7 番目の部分文字列があり、この 7 番目の部分文字列の値が NULL 文字列です。

以下の例は、string 内に NULL 値がある場合を示しています。部分文字列 1 と 3 が抽出されます。これらの部分文字列は存在しますが、両方とも NULL 文字列を含みます。(部分文字列 1 は、最初の区切り文字の前にある文字列として定義されています)。

   SET colorlist=",Red,,Blue,"
   SET extract1=$PIECE(colorlist,",")
   SET extract3=$PIECE(colorlist,",",3)
   WRITE !,"sub1=",extract1,!,"sub3=",extract3

以下の例も、NULL 文字列を返します。指定された部分文字列が存在しないためです。

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   SET extract=$PIECE(colorlist,",",0)
   WRITE !,"Length=",$LENGTH(extract),!,"Value=",extract

   SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
   SET extract=$PIECE(colorlist,",",8,20)
   WRITE !,"Length=",$LENGTH(extract),!,"Value=",extract

数値評価の強制

$PIECE (または任意の ObjectScript 関数) の前に単項 + 符号を配置すると、戻り値の数値評価が強制されます。これは、キャノニック形式で数値部分文字列を返します。これは、非数値部分文字列を 0 として返します。これは、混合数値文字列の先頭の数字部分を返します。これは、NULL 文字列値または存在しない部分文字列について 0 を返します。

この数値評価の強制を以下の例で示します。

  SET str="snow white,7dwarves,+007.00,99.90,,-0,"
  WRITE "Substrings:",!
  FOR i=1:1:7 {WRITE i,"=",$PIECE(str,",",i)," "}
  WRITE !,"Forced Numerics:",!
  FOR i=1:1:7 {WRITE i,"=",+$PIECE(str,",",i)," "}

入れ子になった $PIECE 処理

複雑な抽出を実行するには、$PIECE 参照を相互に入れ子にすることができます。内側の $PIECE は、外側の $PIECE によって処理される部分文字列を返します。各 $PIECE はそれぞれの区切り文字を使用します。例えば、以下は州の略語である "MA" を返します。

   SET patient="John Jones/29 River St./Boston MA 02095"
   SET patientstateaddress=$PIECE($PIECE(patient,"/",3)," ",2)
   WRITE patientstateaddress

以下は、入れ子になった $PIECE 処理のもう 1 つの例で、区切り文字の階層が使用されています。最初に、内側の $PIECE がキャレット (^) の区切り文字を使用して、nestlist の 2 番目の部分文字列である "A,B,C" を見つけます。次に、外側の $PIECE がコンマ (,) 区切り文字を使用して、部分文字列 "A,B,C" の最初と 2 番目の部分文字列 ("A,B") を返します。

   SET nestlist="1,2,3^A,B,C^@#!"
   WRITE $PIECE($PIECE(nestlist,"^",2),",",1,2)

$EXTRACT および $LIST と比較した $PIECE コマンド

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

$EXTRACT は、文字列の最初の部分から文字をカウントすることにより、部分文字列を決定します。$EXTRACT は、入力として通常の文字列を取ります。

$LIST は、リストの最初から要素 (文字ではない) をカウントすることにより、エンコードされたリストから要素を決定します。$LIST 関数は、特定の区切り文字を使用せずに部分文字列を指定します。区切り文字または区切り文字シーケンスを除外することが特定のデータ型 (ビット文字列データなど) で不適切な場合は、$LISTBUILD と $LIST 関数を使用して部分文字列の格納と検索を行ってください。区切り文字列は、$LISTFROMSTRING 関数を使用してリストに変換できます。リストは、$LISTTOSTRING 関数を使用して区切り文字列に変換できます。

$PIECE 関数と $LIST 関数によって使用されるデータ格納方法は互換性がなく、組み合わせて使用することはできません。例えば、$LISTBUILD を使用して作成されたリストに対して $PIECE を使用すると、予測できない結果を生じる場合があるため、使用しないでください。