Caché Basic Reference
Piece
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Returns the specified substring, using a delimiter.
Synopsis
Piece(string,delimiter[,from[,to]])

Piece(string,delimiter[,from[,to]])=value
Arguments
string String expression containing substrings to be extracted.
delimiter A delimiter used to identify substrings within string.
from Optional — An integer that specifies the substring, or the beginning of a range of substrings, to return from the target string. Specified as a substring count from the beginning of 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. Specified as a substring count from the beginning of string. Must be used with from.
Description
The Piece function can be used in two ways:
When returning a specified substring (piece) from string, the substring returned depends on the arguments used:
The values for from and to must be positive integers when specified, otherwise the Piece function will return an empty string.
Arguments
string
The target string from which the substring is to be returned. It can be a string literal, a variable name, or any valid Caché Basic 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 on the left hand side of the equals sign, string must evaluate to a valid variable name.
delimiter
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.
from
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 argument is used with the to argument, it identifies the start of a range of substrings to be returned as a string, and should be less than the value of to.
to
The number of the substring within string that ends the range initiated by the from argument. 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 argument must be used with from and should be greater than the value of from.
Replacing a Substring Using Piece
You can use Piece to the left of the equals sign to replace a substring within string. 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) in this context differs from other standard functions because it modifies an existing value, instead of just returning a value.
Replacing a Delimited Substring
The following example changes the value of colorlist to "Red,Cyan,Yellow,Green,Orange,Purple,Black":
colorlist="Red,Blue,Yellow,Green,Orange,Purple,Black"
PrintLn colorlist
Piece(colorlist,",",2)="Cyan"
PrintLn colorlist
 
The replacement substring may, of course, be longer or shorter than the original.
If you do not specify a from argument, the first substring is replaced:
colorlist="Red,Blue,Yellow,Green,Orange,Purple,Black"
PrintLn colorlist
Piece(colorlist,",")="Crimson"
PrintLn colorlist
 
If you specify a from and to argument, the included substrings are replaced by the specified value, in this case the 4th, 5th, and 6th delimited substrings:
colorlist="Red,Blue,Yellow,Green,Orange,Purple,Black"
PrintLn colorlist
Piece(colorlist,",",4,6)="non-primary colors"
PrintLn 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 smallcolor to "Green;Blue;;Red". The number of delimiter characters added is equal to the from value, minus the number of existing delimiters, minus one:
smallcolor="Green;Blue"
PrintLn smallcolor
Piece(smallcolor,";",4)="Red"
PrintLn smallcolor
 
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:
colorlist="Red,Green,Blue"
PrintLn colorlist
Piece(colorlist,"^")="Purple^Orange"
PrintLn 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:
colorlist="Red,Green,Blue"
PrintLn colorlist
Piece(colorlist,"^",3)="Purple^Orange"
PrintLn colorlist
 
Delimiter is Null String
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”:
colorlist="Red,Green,Blue"
PrintLn colorlist
Piece(colorlist,"")="Purple"
PrintLn colorlist
 
colorlist="Red,Green,Blue"
PrintLn colorlist
Piece(colorlist,"",3,5)="Purple"
PrintLn colorlist
 
Initializing a String Variable
The string variable does not need to be defined before being assigned a value. The following example initializes newvar to the character pattern ">>>>>>TOTAL":
Piece(newvar,">",7)="TOTAL"
PrintLn newvar
 
Piece with Parameters over 32,768 Characters
If you wish to use Piece with a parameter greater than 32767 characters, long strings must be enabled. Long string support is enabled by default. In the Management Portal navigate to [Home] > [Configuration] > [Memory and Startup] from the System Administration > Configuration > System Configuration menu. To enable support for long strings system-wide, select the Enable Long Strings check box. Then click the Save button.
Examples
The following example returns designated substrings from a string using the “|” character as a delimiter:
MyString = "InterSystems|One Memorial Drive|Cambridge|MA 02142"
Println Piece(MyString, "|") 'InterSystems
Println Piece(MyString, "|", 2) 'One Memorial Drive
Println Piece(MyString, "|", 3, 4) 'Cambridge|MA 02142
Println Piece(Piece(MyString, "|", 4), " ") 'MA
 
The following example performs the same operation using a multicharacter delimiter string:
MyString = "InterSystemslinebreakOne Memorial DrivelinebreakCambridge MAlinebreak02142"
Println Piece(MyString, "linebreak") 'InterSystems
Println Piece(MyString, "linebreak", 2) 'One Memorial Drive
Println Piece(MyString, "linebreak", 3) 'Cambridge MA
Println Piece(MyString, "linebreak", 4,4) '02142
 
See Also