FIELDSTORE()

 Top  Previous  Next

 

The FIELDSTORE() function provides delimited substring assignment. It is closely related to the GROUPSTORE statement.

 

 

Format

 

FIELDSTORE(string, delimiter, i, n, rep.string)

 

where

 

stringevaluates to the string in which replacement is to occur. If string is a variable name, the contents of this variable are not changed unless it also appears on the left hand side of the assignment statement in which the FIELDSTORE() function appears.

 

delimiterevaluates to a string, the first character of which is used as the delimiter separating the substrings within string. A null delimiter string will cause a run time error.

 

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

 

nevaluates to the number of substrings to be replaced.

 

rep.stringevaluates to the new data to be inserted in string.

 

 

The value returned by the FIELDSTORE() function is the result of the replacement.

 

A statement of the form

 

S = FIELDSTORE(S, d, i, n, rep.string)

 

is equivalent to the delimited substring assignment operation

 

S[d, i, n] = rep.string

 

The action of FIELDSTORE() 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 $MODE NOCASE.STRINGS compiler directive makes the delimiter case insensitive.

 

 

Example

 

S = 1*2*3*4*5

A = FIELDSTORE(S, "*", 2, 3, "A*B")

B = FIELDSTORE(S, "*", 2, 3, "A*B*C")

C = FIELDSTORE(S, "*", 2, 3, "A*B*C*D")

D = FIELDSTORE(S, "*", 2, 0, "A*B")

E = FIELDSTORE(S, "*", 2, -3, "A*B")

 

This program fragment performs the FIELDSTORE() function on the string S using different values for rep.string and n. The results are

 

A = 1*A*B**5Note inserted delimiter as rep.string has only 2 substrings
B = 1*A*B*C*5rep.string replaces substrings 2 to 5
C = 1*A*B*C*5Final substring of rep.string is not inserted
D = 1*A*B*2*3*4*5No substrings are deleted as n is zero
E = 1*A*B*5Three substrings are deleted and rep.string is inserted

 

 

See also:

FIELD(), GROUPSTORE