Skip to main content
Previous sectionNext section

Piece

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:

  • To return a substring or a range of substrings from string. The substring is determined by specifying a delimiter character (or character string) that is found in string. This uses the Piece(string,delimiter,from,to) syntax.

  • To replace a substring within string. The replacement substring may be the same length, longer, or shorter than the original substring. The substring is determined by specifying a delimiter character (or character string) that is found in string. This uses the Piece(string,delimiter,from,to)=value syntax.

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

  • Piece(string,delimiter) returns the first substring in string. If delimiter occurs in string, this is the substring that precedes the first occurrence of delimiter. If delimiter does not occur in string, the returned substring is string.

  • Piece(string,delimiter,from) returns the substring which is the nth piece of string, where the integer n is specified by the from argument, and pieces are separated by a delimiter. The delimiter is not returned.

  • Piece(string,delimiter,from,to) returns a range of substrings including the substring specified in from through the substring specified in to. This four-argument form of Piece returns a string that includes any intermediate occurrences of delimiter that occur between the from and to substrings. If to is greater than the number of substrings, the returned substring includes all substrings to the end of string.

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 omitted or set to 1, Piece returns the first substring of string. If string does not contain the specified delimiter, a from value of 1 returns string.

  • If the from argument identifies by count the last substring in string, this substring is returned, regardless of whether it is followed by a delimiter.

  • If the value of from is the null string (""), zero, a negative number, or greater than the number of substrings in string, Piece returns a null string.

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.

  • If from is less than to, Piece returns a string consisting of all of the delimited substrings within this range, including the from and to substrings. This returned string contains the substrings and the delimiters within this range.

  • If to is greater than the number of delimited substrings, the returned string contains all the string data (substrings and delimiters) beginning with the from substring and continuing to the end of the string string.

  • If from is equal to to, the from substring is returned.

  • If from is greater than to, Piece returns a null string.

  • If to is the null string (""), Piece returns a null string.

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard
colorlist="Red,Green,Blue"
PrintLn colorlist
Piece(colorlist,"",3,5)="Purple"
PrintLn colorlist
Copy code to clipboard

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
Copy code to clipboard

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 System, 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
Copy code to clipboard

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
Copy code to clipboard

See Also