GROUPSTORE Statement

Inserts a group (a substring delimited by an attribute mark or other specified character) from one string into another string replacing all, part, or none of the second string.

Syntax

GROUPSTORE char-string1 IN char-string2 USING start#,replace# {,delim-char}

Syntax Elements

char-string1 is the name of the string containing the substring to be inserted into char-string2.

char-string2 is the name of the string into which the substring is inserted; expressed as a variable name or a dynamic array reference.

start# is the position of the first group in char-string2 to be replaced.

If start# is specified as 0, it defaults to 1.

If start# is less than zero, its absolute magnitude is used.

If start# is greater than the number of groups in char-string2, as many null groups as necessary is added and the replacement groups are appended to the end of char-string2.

replace# is the number of groups in char-string2 to replace with groups from char-string1, according to the following rules, where r is replace#:

r > 0 Groups of char-string2 are replaced by the first r groups in char-string1. If r is greater than the number of groups in char-string1, replacement stops when char-string1 is exhausted.

r = 0 All of char-string1 is inserted before the start# group in char-string2.

r < 0 The number of groups specified by the absolute magnitude of r are deleted from char-string2, starting with the start# group. All of char-string1 is inserted at this position (unless start# is also less than zero, in which case nothing is inserted.

delim-char is a single character used to delimit groups in both char-string1 and char-string2. If delim-char is not specified, it defaults to an attribute mark. If more than one character is specified as delim-char, only the first character is used.

Comments

The GROUPSTORE statement and the GROUP function are related. The GROUP function extracts elements from a string while the GROUPSTORE statement inserts elements into a string.

Examples

X = "123DEF"
GROUPSTORE "ABC" IN X USING 1,1

Replaces the value 123DEF in string X with ABC, so X = "ABC".

A = "10X"
B = "XXXXXXXXXXX"
GROUPSTORE A IN B USING 1,3

Replaces the current value of B (attribute 1) with the string "10X". Although 3 replacements were specified, only 1 replacement was made as the string was exhausted.

A = "ABC456"
GROUPSTORE "123" IN A USING 1,0
.
.
.

The new value of A is 123^ABC456. Because the replace# = 0, the replacement string is inserted before the existing string.

STR = "44^88^99]2\7\4^8^99
GROUPSTORE "ABC" IN STR USING 3,1
PRINT STR

Prints 44^88^ABC^8^99.

A="ABCXLMNXGHIXJKL"
B="DEF"
Z="X"
GROUPSTORE B IN A USING 2,1,Z
PRINT A

Prints ABCXDEFXGHIXJKL. Replaced the second element of A (delimited by X) with DEF.