Caché ObjectScript Reference - InterSystems Documentation

Caché ObjectScript FunctionstoThe number of the substring within plist that ends the range initiated by the from parameter.The returned string includes both the from and to substrings, as well as any intermediatesubstrings 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 toparameter 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 substringswithin this range, including the from and to substrings. This returned string contains thesubstrings and the delimiters within this range.• If to is greater than the number of delimited substrings, the returned string contains allthe string data (substrings and delimiters) beginning with the from substring and continuingto the end of the plist 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.ExamplesThe 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 extractThe 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 extractThe following example returns "Blue,Yellow,Orange", the third through fifth substrings incolorlist, as delimited by ",":SET colorlist="Red,Green,Blue,Yellow,Orange,Black"SET extract=$PIECE(colorlist,",",3,5)WRITE extractThe following WRITE statements all return the first substring “123”, showing that theseformats 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)282 Caché ObjectScript Reference