$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	The target string from which a substring is to be returned.
delimiter	A delimiter used to identify substrings within string.
from	Optional — An integer that specifies the substring, or beginning of a range of substrings, to return from the target string. Substrings are separated by a delimiter, and counted from 1. If omitted, the first substring is returned.
to	Optional — An integer that specifies the ending substring for a range of substrings to return from the target string. Must be used with from.

$PIECE can be used in two ways:

When returning a specified substring (piece) from string, the substring returned depends on the parameters used:

Note:

$PIECE is a general-purpose function for handling a string containing delimited substrings. For handling a MultiValue dynamic array string containing the specific MultiValue delimiters, use the $MV function.

The target string from which the substring is to be returned. It can be a string literal, a variable name, or any valid Caché ObjectScript expression that evaluates to a string. If you specify a null string ("") as the target string, $PIECE returns the null string.

A target string usually contains instances of a character (or character string) which are used as delimiters. This character or string cannot also be used as a data value within string.

When $PIECE is used with SET on the left hand side of the equals sign, string must evaluate to a valid variable name.

The search string to be used to delimit substrings within string. It can be a numeric or string literal (enclosed in quotation marks), the name of a variable, or an expression that evaluates to a string.

Commonly, a delimiter is a designated character which is never used within string data, but is set aside solely for use as a delimiter separating substrings. A delimiter can also be a multi-character search string, the individual characters of which can be used within string data.

If the specified delimiter is not in string, $PIECE returns the entire the string string. If the specified delimiter is the null string (""), $PIECE returns the null string.

The number of a substring within string, counting from 1. It must be a positive integer, the name of an integer variable, or an expression that evaluates to a positive integer. Substrings are separated by delimiters.

If the from parameter is used with the to parameter, it identifies the start of a range of substrings to be returned as a string, and should be less than the value of to.

The number of the substring within string that ends the range initiated by the from parameter. The returned string includes both the from and to substrings, as well as any intermediate substrings and the delimiters separating them. The to argument must be a positive integer, the name of an integer variable, or an expression that evaluates to a positive integer. The to parameter must be used with from and should be greater than the value of from.

When making assignments with the SET command, you can use $PIECE to the left, as well as to the right, of the equals sign. When used to the left of the equals sign, $PIECE designates a substring to be replaced by the assigned value.

The use of $PIECE (and $LIST and $EXTRACT) in this context differs from other standard functions because it modifies an existing value, instead of just returning a value.

The following example changes the value of colorlist to "Red,Green,Cyan,Yellow,Orange,Black":

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

The replacement substring may, of course, be longer or shorter than the original:

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

If you do not specify a from argument, the first substring is replaced:

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

If you specify a from and to argument, the included substrings are replaced by the specified value, in this case the 4th through 6th delimited substrings:

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

If $PIECE specifies more occurrences of the delimiter than exist in the target variable, it appends additional delimiters to the end of the value, up to one less than the specified number. The following example changes the value of colorlist to "Green^Blue^^Red". The number of delimiter characters added is equal to the from value, minus the number of existing delimiters, minus one:

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

If delimiter doesn't appear in string, $PIECE treats string as a single piece and performs the same substitutions described above. If there is no from argument specified, the new value replaces the original string:

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

If delimiter doesn't appear in string, and from is specified, $PIECE may append delimiters to the end of string and append the new value to string, to fulfill the from value:

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

If the delimiter is the null string, the new value replaces the original string, regardless of the values of the from and to arguments.

The following two examples both set colorlist to “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

The string variable does not need to be defined before being assigned a value. The following example initializes newvar to the character pattern ">>>>>>TOTAL":

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

See the "SET with $PIECE and $EXTRACT" section of the SET command documentation for more information.

The following example creates a string of 5 periods and a null:

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

Now consider the following example that creates a string of 32767 periods and a null:

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

Although technically within the maximum length of a string, this example generates a <MAXSTRING> error. If you wish to use $PIECE with a parameter greater than 32767 characters, you must enable support for long strings. You can enable long strings system-wide by setting the EnableLongStrings property of the Config.Miscellaneous class.

The following example returns "Red", the first substring as identified by the "," delimiter:

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

The following example returns "Blue”, the third substring as identified by the "," delimiters:

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

The following example returns "Blue,Yellow,Orange", the third through fifth substrings in colorlist, as delimited by ",":

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

The following WRITE statements all return the first substring “123”, showing that these formats are equivalent when from and to have a value of 1:

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

In the following example, both $PIECE functions returns the entire string string, because there are no occurrences of delimiter in string:

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

The following two examples use more complex delimiters.

This example uses a delimiter string “#-#” to return three substrings of the string numlist. Here, the component characters of the delimiter string, “#” and “-”, can be used as data values; only the specified sequence of characters (#-#) is set aside:

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

The following example uses a non-keyboard delimiter character (in this case, the Unicode character for pi), specified using the $CHAR function, and inserted into string by using the concatenate operator (_):

   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

$PIECE is typically used to "unpack" data values that contain multiple fields delimited by a separator character. Typical delimiter characters include the slash (/), the comma (,), the space ( ), and the semicolon (;). The following sample values are good candidates for use with $PIECE:

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

The two-argument form of $LENGTH returns the number of substrings in a string, based on a delimiter. Use $LENGTH to determine the number of substrings in a string, and then use $PIECE to extract individual substrings, as shown in the following example:

   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!"

$PIECE does not distinguish between a delimited substring with a null string value, and a nonexistent substring. Both return a null string value. For example, the following examples both return the null string for a from value of 7:

   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

In the first case, there is no seventh substring; a null string is returned. In the second case there is a seventh substring, as indicted by the delimiter at the end of the string; the value of this seventh substring is the null string.

The following example shows null values within a string. It extracts substrings 1 and 3. These substrings exists, but both contain a null string. (Substring 1 is defined as the string preceding the first delimiter character):

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

The following examples also returns a null string, because the specified substrings do not exist:

   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

To perform complex extractions, you can nest $PIECE references within each other. The inner $PIECE returns a substring that is operated on by the outer $PIECE. Each $PIECE uses its own delimiter. For example, the following returns the state abbreviation “MA”:

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

The following is another example of nested $PIECE operations, using a hierarchy of delimiters. First, the inner $PIECE uses the caret (^) delimiter to find the second piece of nestlist: "A,B,C". Then the outer $PIECE uses the comma (,) delimiter to return the first and second pieces ("A,B") of the substring "A,B,C":

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

$PIECE determines a substring by counting user-defined delimiter characters within the string. $PIECE takes as input an ordinary character string containing multiple instances of a character (or string) intended for use as a delimiter.

$EXTRACT determines a substring by counting characters from the beginning of a string. $EXTRACT takes as input an ordinary character string.

$LIST determines an element from an encoded list by counting elements (not characters) from the beginning of the list. The $LIST functions specify substrings without using a designated delimiter. If setting aside a delimiter character or character sequence is not appropriate to the type of data (for example, bitstring data), you should use the $LISTBUILD and $LIST functions to store and retrieve substrings. You can convert a delimited string into a list using the $LISTFROMSTRING function. You can convert a list to a delimited string using the $LISTTOSTRING function.

The data storage methods used by $PIECE and the $LIST functions are incompatible and should not be combined. For example, attempted to use $PIECE on a list created using $LISTBUILD yields unpredictable results and should be avoided.


	[Documentation] > [Development References] > [ObjectScript Reference] > [ObjectScript Functions] > [$PIECE]		Go to:		Search: