1つ以上の文字で構成された指定された区切り文字によって、区切られた部分文字列を返します。Mでは、$PIECE() は論理レコードから論理フィールドを返します。
$PIECE関数のフォーマット:
$P[IECE](expr1,expr2[,intexpr1[,intexpr2]])
最初の式(expr1) は、$PIECE() がその結果を計算する元となる文字列を指定します。
2番目の式(expr2)は、"境界" 位置を決定する区切り文字列を指定します; もしこの引数が空文字列の場合、$PIECE() は空の文字列を返します。
もし2番目の式(expr2)が最初の式のどこにも表示されない場合は、$PIECE() は、最初の式の全体を返します(2つ目の整数式で空の文字列を返すように強制されない限り)。
オプションの最初の整数式(3番目の引数)は、返すための開始部分文字を指定します; もしこの引数が欠落している場合、$PIECE() は最初の部分文字を返します。
オプションの2番目の整数式(4番目の引数)は、返すための最後の部分文字を指定します。もしこの引数が欠落している場合、それがヌル文字列を返す場合には、最初の整数式がゼロ(0)または負でない限りは、$PIECE() は部分文字1つのみを返します。もしこの引数が最初の整数の式より小さい場合、$PIECE() は、空の文字列を返します。
もし2番目の整数式が最初の式で部分文字の実際の数を超える場合、$PIECE() は、最初に整数式によって選択されたデリミタの後の式のすべてを返します。
$PIECE()の結果は、"外部:outside" の区切り文字を決して含んでいません; ただし、2番目の整数の引数が複数の部分文字を指定しているとき、結果は、区切り文字の "内側:inside" の出現を含んでいます。
$PIECE() は、長さが可変であるそれぞれが複数のエレメントまたはフィールドが含まれている値を効果的に使用するツールとして使用することもできます。
アプリケーションは、通常、ストレージのオーバーヘッドを最小限に抑えるために、$PIECE() 区切り文字(2番目の引数)に単一の文字を使用し、そして、実行時の効率を向上させます。データ値は区切り文字を決して含まないので、区切り文字を選択する必要があります。編集のチェックでこの習慣を強制することの障害は、データ値内の部分文字列の位置に予期しない変更が発生する可能性があります。キャレット記号(^)、バックスラッシュ(\)、アスタリスク(*)文字は、良く利用する目に見える区切り文字の例です。複数文字のデリミタは、フィールドの内容とのコンフリクトの可能性を減らすことができます。しかし、それらはストレージの効率性を低下させ、単一文字の区切り文字よりも効率性は少なく処理されます。一部のアプリケーションでは、データに現れる区切り文字の可能性は減らせ、目に見える区切り文字で提供される読みやすさが犠牲になりますが、制御文字が使用できます。
SETコマンドの引数は、その等号(=)の左辺の$PIECE() のフォーマットを持っている何かを持つことができます。この構文は、文字列内のそれぞれの部分を容易にメンテナンスが可能です。また、区切り文字の文字列を生成するために使用することもできます。SET $PIECE() の詳細については、 “Set”を参照してください。
$PIECE() は、ノードの値の一部を変更するには、SET コマンドのターゲットとして使用することもできます。また、SETの引数が括弧(setの左側)で括られた複数のターゲットをもち、ターゲットがそれに続くターゲットのリストで複数の項目に添字として使用されている時は、すべてのターゲットは、M標準規格に準拠した、SETの前の値(SETの後の値ではない) を使用します。SET $PIECE() の詳細については、 “Set”を参照してください。
プロセスがUTF-8モードで起動する場合、$PIECE() はUTF-8 エンコードとして文字列の引数を解釈します。VIEW "BADCHAR" が"有効で、それが不正な形式の文字を検出したときに、$PIECE() は実行時エラーを生成しますが、しかし、それは引数で指定された範囲の後に入る文字を処理しません。
$ZPIECE() は、$PIECE() の併用可能な関数です。VIEW "BADCHAR" と $ZCHSETの設定に関係なく、$ZPIECE() は、バイトシーケンス(むしろ文字シーケンスより)として文字列の引数を解釈し、バイト指向の$PIECE() 操作を実行することができます。詳細な情報については、 “$ZPiece()”を参照してください。
例:
GTM>for i=0:1:3 write !,$piece("1 2"," ",i),"<" < 1< 2< < GTM>
このループは、、区切り文字としてスペース、部分文字列の位置の "前"の文字、1番目と2番目の文字、そして、"後" の文字を指定して、$PIECE() の結果を表示します。
例:
GTM>for i=-1:1:3 write !,$piece("1 2"," ",i,i+1),"<" < 1< 1 2< 2< < GTM>
この例では、それぞれの繰り返しで、2つの部分文字を表示することを除いて、前の例と似ています。両方の部分文字を表示する3番目の繰り返しにおいて出力の途中に区切り文字(スペース)に注意してください。
例:
for p=1:1:$length(x,"/") write ?p-1*10,$piece(x,"/",p)
この例では、カラムフォーマットで、x のすべての部分文字を表示するために $LENGTH() と $PIECE() を使用しています。
例:
GTM>set $piece(x,".",25)="" write x ........................
これは、ピリオドの区切り文字で、変数 x の25番目をnullにSETします。これは、null に続く24個のピリオドの文字列を生成します。
例:
GTM>set ^x=1,$piece(^a,";",3,2)=^b
この例では、グローバル ^b で示されたネイキッドインジケータを残します。