第四十九章 Caché 函数大全 $PIECE 函数

第四十九章 Caché 函数大全 $PIECE 函数

使用定界符返回或替换子字符串。

大纲

$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 标识分隔的子字符串的目标字符串。将字符串指定为计算结果为带引号的字符串或数字值的表达式。在SET $PIECE语法中，字符串必须是变量或多维属性。
• 用于标识字符串中子字符串的定界符。将定界符指定为一个表达式，该表达式的结果为包含一个或多个字符的带引号的字符串。
• from 可选-表达式的计算结果为指定字符串中子字符串的位置或子字符串范围的开头的代码。子字符串由定界符分隔，并从1开始计数。允许的值为n（正整数，指定从字符串开头的子字符串计数），*（指定字符串中的最后一个子字符串）和* -n（偏移整数计数）。从字符串末尾开始倒数的子字符串）。 SET $PIECE语法还支持* + n（要追加到字符串末尾的子字符串的偏移整数计数）。因此，第一个定界子串是1，第二个定界子串是2，最后一个定界子串是*，倒数第二个定界子串是* -1。如果忽略from，则默认为第一个带分隔符的子字符串。
• to 可选—一个表达式，其计算结果为指定字符串中一系列子字符串的结尾子字符串的代码。必须与from一起使用。允许的值为n（从字符串开头指定子字符串计数的正整数），*（指定字符串中最后一个子字符串）和* -n（从字符串末尾偏移的子字符串整数）。 SET $PIECE语法还支持* + n（用于附加到字符串末尾的一系列子字符串的偏移整数）。如果to在字符串中位于from之前，则不执行任何操作，也不产生错误。

描述

$PIECE通过分隔符的存在来标识字符串中的子字符串。如果分隔符未出现在字符串中，则整个字符串将被视为单个子字符串。

$PIECE可以通过两种方式使用：

• 从字符串返回子字符串。这使用$PIECE(string,delimiter,from,to)语法。
• 替换字符串中的子字符串。它标识一个子字符串并将其替换为另一个子字符串。替换子字符串的长度可以与原始子字符串相同，更长或更短。这使用$PIECE(string,delimiter,from,to) = value 语法。

注意：$PIECE是用于处理包含定界子字符串的字符串的通用函数。若要处理包含特定MultiValue定界符的MultiValue动态数组字符串，请使用$MV函数。

返回一个子字符串。

从字符串返回指定的子字符串（片断）时，返回的子字符串取决于所使用的参数：

• $PIECE(string,delimiter)返回字符串中的第一个子字符串。如果定界符出现在字符串中，则这是第一次出现定界符之前的子字符串。如果字符串中未出现定界符，则返回的子字符串为字符串。
• $PIECE(string,delimiter,from)返回一个子字符串，其位置由from参数指定。子字符串由定界符以及字符串的开头和结尾定界。分隔符本身不返回。
• $PIECE(string,delimiter,from,to)返回一系列子字符串，包括从中指定的子字符串到in至（包括）中指定的子字符串。 $PIECE的这种四参数形式返回一个子字符串，该子字符串包括在from和to子字符串之间出现的定界符的任何中间出现。如果to大于子字符串的数量，则返回的子字符串将包括字符串末尾的所有子字符串。

参数

string

当使用$PIECE返回子字符串时，string可以是用引号引起来的字符串文字，规范数字，变量，对象属性或任何求值为字符串或数字的有效ObjectScript表达式。如果将空字符串（“”）指定为目标字符串，则$PIECE始终返回该空字符串，而不考虑其他参数值。

目标字符串通常包含用作分隔符的字符（或字符串）实例。此字符或字符串也不能用作字符串中的数据值。

当$PIECE与等号左侧的SET一起使用以替换子字符串时，string可以是变量或多维属性引用。它不能是非多维对象属性。

delimiter

用于在字符串中定界子字符串的搜索字符串。它可以是用引号引起来的字符串文字，规范的数字，变量或任何有效的ObjectScript表达式（其结果为字符串或数字）。

通常，定界符是一个指定字符，从不用作字符串中的数据，而是专门留出用作分隔子字符串的定界符。例如，如果定界符为“^”，则字符串“Red^Orange^Yellow”包含三个定界子字符串。

分隔符可以是多字符字符串，可以在字符串数据中使用其各个字符。例如，如果定界符为“^＃”，则字符串“Red^Orange^#^Yellow#Green#^Blue”包含两个定界子字符串：“Red^Orange”和“^Yellow#Green#^Blue”。

通常，字符串不以定界符开头或结尾。如果字符串以分隔符开始或结束，则$PIECE将此分隔符视为使用空字符串（“”）值划分子字符串。例如，如果定界符为“^”，则字符串“^Red^Orange^Yellow^” 包含五个定界子字符串；子字符串1和5具有空字符串值。

如果指定的定界符不在字符串中，则$PIECE返回整个字符串。如果指定的分隔符是空字符串（“”），则$PIECE返回空字符串。

from

子字符串在字符串中的位置。使用n（正整数）从字符串开头算起定界的子字符串。使用*指定字符串中最后一个定界的子字符串。使用* -n通过与字符串中最后一个分隔的子字符串的偏移量来计数分隔的子字符串。

• 1指定字符串的第一个子字符串（在第一次出现定界符之前的子字符串）。如果string不包含指定的分隔符，则from值1将返回string。如果忽略from，则默认为1。
• 2指定字符串的第二个子字符串（出现在分隔符的第一次和第二次出现之间，或第一次出现的分隔符和字符串结尾之间的子字符串）。
• *指定字符串的最后一个子字符串（最后一次出现定界符之后的子字符串）。如果string不包含指定的分隔符，则from值*会返回string。
• *-1指定字符串的倒数第二个子字符串。 * -n通过相对于字符串最后一个子字符串的偏移量进行计数。 * -0是字符串的最后一个子字符串； *和* -0在功能上相同。
• 仅适用于SET $PIECE语法— * + n（星号后跟一个正数）将定界的子字符串附加偏移量，超出字符串末尾。因此，* + 1在字符串末尾附加一个带分隔符的子字符串，* + 2在字符串末尾两个位置附加一个分隔的子字符串，并用定界符填充。
• 如果from是空字符串（“”），零，负数，或者指定了超出字符串中子字符串数量的计数或偏移量，则$PIECE返回空字符串。

$PIECE将a从数字形式转换为规范形式（解析前导正负号并删除前导零），然后将其截断为整数。

如果from参数与to参数一起使用，则它将标识要作为字符串返回的子字符串范围的开始，并且应小于to的值。

to

字符串中子字符串的编号，该字符串终止由from参数启动的范围。返回的字符串包括from和to子字符串，以及任何中间子字符串和分隔它们的定界符。 to参数必须与from一起使用，并且应大于from的值。

使用n（正整数）从字符串开头算起定界的子字符串。使用*指定字符串中最后一个定界的子字符串。使用* -n通过从字符串中最后一个带分隔符的子字符串向后偏移来计数带分隔符的子字符串。

仅对于SET $PIECE语法-* + n（星号后跟一个正数）指定要附加到字符串末尾之外的子字符串范围的末尾。

• 如果from小于to，则$PIECE返回一个字符串，该字符串包括此范围内的所有带分隔符的子字符串，包括from和to子字符串。返回的字符串包含此范围内的子字符串和定界符。如果to大于分隔的子字符串的数量，则返回的字符串包含从from子字符串开始，一直到字符串末尾的所有字符串数据（子字符串和定界符）。
• 如果from等于to，则$PIECE返回from子字符串。如果from和to是相同的值，或者是引用相同子字符串的不同值，则可能发生这种情况。
• 如果from大于to，为零（0），或者为空字符串（“”），则$PIECE返回一个空字符串。

$PIECE将a转换为标准格式（解析前导正负号并删除前导零），然后将其截断为整数。

指定* -n和* + n参数值

使用变量指定* -n或* + n时，必须始终在参数本身中指定星号和符号字符。

以下是* -n的有效规格：

/// d ##class(PHA.TEST.Function).PIECE()
ClassMethod PIECE()
{
    SET count=2
    SET alph="a^b^c^d"
    WRITE $PIECE(alph,"^",*-count)
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE()
b

/// d ##class(PHA.TEST.Function).PIECE1()
ClassMethod PIECE1()
{
    SET count=-2
    SET alph="a^b^c^d"
    WRITE $PIECE(alph,"^",*+count)
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE1()
b

以下是* + n的有效规范：

/// d ##class(PHA.TEST.Function).PIECE2()
ClassMethod PIECE2()
{
    SET count=2
    SET alph="a^b^c^d"
    SET $PIECE(alph,"^",*+count)="F"
    WRITE alph
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE2()
a^b^c^d^^F

这些参数值内允许使用空格。

示例：返回带分隔符的子字符串

在下面的示例中，每个$PIECE返回指定的子字符串，该子字符串由“，”定界符标识：

/// d ##class(PHA.TEST.Function).PIECE3()
ClassMethod PIECE3()
{
    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
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE3()
Red
Blue
Black
Orange

在下面的示例中，$PIECE返回数字的整数和小数部分：

/// d ##class(PHA.TEST.Function).PIECE4()
ClassMethod PIECE4()
{
    SET int=$PIECE(123.999,".")
    SET frac=$PIECE(123.999,".",*)
    WRITE "integer=",int," fraction =.",frac
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE4()
integer=123 fraction =.999

下面的示例返回“Blue，Yellow，Orange”，即颜色列表中的第三到第五个子字符串，用“，”分隔：

/// d ##class(PHA.TEST.Function).PIECE5()
ClassMethod PIECE5()
{
    SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
    SET extract=$PIECE(colorlist,",",3,5)
    WRITE extract
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE5()
Blue,Yellow,Orange

以下WRITE语句均返回第一个子字符串“123”，表明当from的值等于1时，这些格式是等效的：

/// d ##class(PHA.TEST.Function).PIECE6()
ClassMethod PIECE6()
{
    SET numlist="123#456#789"
    WRITE !,"2-arg=",$PIECE(numlist,"#")
    WRITE !,"3-arg=",$PIECE(numlist,"#",1)
    WRITE !,"4-arg=",$PIECE(numlist,"#",1,1)
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE6()
 
2-arg=123
3-arg=123
4-arg=123

在下面的示例中，两个$PIECE函数都返回整个字符串字符串，因为在字符串中没有出现定界符：

/// d ##class(PHA.TEST.Function).PIECE7()
ClassMethod PIECE7()
{
    SET colorlist="Red,Green,Blue,Yellow,Orange,Black"
    SET extract1=$PIECE(colorlist,"#")
    SET extract2=$PIECE(colorlist,"#",1,4)
    WRITE "#   =",extract1,!,"#,1,4=",extract2
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE7()
#   =Red,Green,Blue,Yellow,Orange,Black
#,1,4=Red,Green,Blue,Yellow,Orange,Black

以下示例$PIECE从对象属性返回第二个子字符串：

/// d ##class(PHA.TEST.Function).PIECE8()
ClassMethod PIECE8()
{
    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),!
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE8()
whole schema path: MyTests,Sample,Cinema
2nd piece of schema path: Sample
 

以下两个示例使用更复杂的定界符。

本示例使用定界符字符串“＃-＃”返回字符串numlist的三个子字符串。此处，定界字符串的组成字符“＃”和“-”可用作数据值；仅保留指定的字符序列（＃-＃）：

/// d ##class(PHA.TEST.Function).PIECE9()
ClassMethod PIECE9()
{
    SET numlist="1#2-3#-#45##6#-#789"
    WRITE !,$PIECE(numlist,"#-#",1)
    WRITE !,$PIECE(numlist,"#-#",2)
    WRITE !,$PIECE(numlist,"#-#",3)
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE9()
 
1#2-3
45##6
789

下面的示例使用一个非ASCII分隔符（在本例中为pi的Unicode字符），该字符通过$CHAR函数指定，并通过连接运算符（_）插入到字符串中：

/// d ##class(PHA.TEST.Function).PIECE10()
ClassMethod PIECE10()
{
    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 "此示例需要Caché的Unicode安装"
    }
}

DHC-APP>d ##class(PHA.TEST.Function).PIECE10()
Red
Green
GreenπBlue

使用SET $PIECE替换子字符串

使用SET命令进行分配时，可以在等号的左侧和右侧使用$PIECE。在等号左侧使用时，$PIECE指定要由分配的值替换的子字符串。

当$PIECE与等号左侧的SET一起使用时，字符串可以是有效的变量名。如果该变量不存在，则SET $PIECE对其进行定义。字符串参数也可以是多维属性引用。它不能是非多维对象属性。尝试在非多维对象属性上使用SET $PIECE会导致