$PIECE(string,delimiter,from,to)
$P(string,delimiter,from,to)
SET $PIECE(string,delimiter,from,to)=value
SET $P(string,delimiter,from,to)=value
引数
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 文字) を使用します。
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
SET $PIECE を使用した部分文字列の置換
SET コマンドを使用して値を代入するとき、等号の右側と同様、左側にも $PIECE を使用できます。$PIECE は、等号の左側に使用されると、代入値で置き換えられる部分文字列の値を示します。
等号の左側で SET と共に $PIECE を使用する場合、string は有効な変数名にすることができます。変数が存在しない場合は、SET $PIECE が変数を定義します。string 引数は、多次元プロパティ参照にすることもできますが、非多次元オブジェクト・プロパティにすることはできません。非多次元オブジェクト・プロパティで SET $PIECE を使用しようとすると、<OBJECT DISPATCH> エラーが発生します。
このコンテキストで $PIECE ($LIST および $EXTRACT) を使用すると、単に値を返すだけではなく、既存の値を変更してしまうため、他の基本関数とは異なります。$PIECE (または $LIST や $EXTRACT) を伴った SET (a,b,c,...)=value 構文は、その関数で相対オフセット構文 * (文字列の末尾を表す)、*-n または *+n (文字列の末尾からの相対オフセットを表す) を使用する場合、等号の左側では使用できません。その代わりに、SET a=value,b=value,c=value,... 構文を使用する必要があります。
例 : 区切り部分文字列を置換する方法
以下の例は、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 が文字列の先頭より前の位置を指している場合は、InterSystems IRIS は何の処理も実行しません。
SET colorlist="Red,Green,Blue"
WRITE colorlist,!
SET $PIECE(colorlist,",",*-7)="Purple"
WRITE colorlist
from が文字列の先頭より前の位置を指しており、to が指定されている場合は、InterSystems IRIS は 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
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 処理
複雑な抽出を実行するには、$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)