GROUPSTORE

The GROUPSTORE statement inserts, deletes or replaces elements of a delimited string. It is closely related to the FIELDSTORE() function.

Format

GROUPSTORE rep.string IN string USING i, n {, delimiter}

where

rep.string

evaluates to the new data to be inserted in string.

string

is the string in which replacement is to occur.

i	evaluates to the position of the first substring to be replaced. Substring positions are numbered from one.

n	evaluates to the number of substrings to be replaced.

delimiter

evaluates to a string, the first character of which is used as the delimiter separating the substrings within string. If omitted, a field mark is used.

The action of GROUPSTORE depends on the values of i and n and the number of substrings within rep.string.

If the value of the position expression, i, is less than one, a value of one is assumed. If there are fewer than i delimited substrings present in string, additional delimiters are added to reach the required position.

If the value of the number of substrings expression, n, is positive, n substrings are replaced by the same number of substrings from rep.string. If rep.string contains fewer than n substrings, additional delimiters are inserted.

If the value of the number of substrings expression, n, is zero or negative, n substrings are deleted from string and the whole of rep.string is inserted regardless of the number of substrings that it contains.

Use of the $NOCASE.STRINGS compiler directive makes the delimiter case insensitive.

Example

Each of the following examples assumes variable S is initialised with

S = "1*2*3*4*5"

before the GROUPSTORE is executed.

GROUPSTORE "A*B" IN S USING 2, 3, "*"

Variable S becomes "1*A*B**5". Note the inserted delimiter as rep.string has only 2 substrings.

GROUPSTORE "A*B*C" IN S USING 2, 3, "*"

Variable S becomes "1*A*B*C*5". rep.string replaces substrings 2 to 5.

GROUPSTORE "A*B*C*D" IN S USING 2, 3, "*"

Variable S becomes "1*A*B*C*5". Final substring of rep.string is not inserted.

GROUPSTORE "A*B" IN S USING 2, 0, "*"

Variable S becomes "1*A*B*2*3*4*5". No substrings are deleted as n is zero.

Note

GROUPSTORE "A*B" IN S USING 2, -3, "*"

Variable S becomes "1*A*B*5". Three substrings are deleted and rep.string is inserted