FIELDSTORE
Synopsis
FIELDSTORE(string,delimiter,count,multiple,newval)
Arguments
| string | An expression that resolves to a string. The source string to be modified. string can be a dynamic array. |
| delimiter | An expression that resolves to a single character that serves as a delimiter within string |
| count | An expression that resolves to an integer that specifies which delimited string to use as the starting point for the replacement operation. |
| multiple | An expression that resolves to an integer specifying how many delimited strings to replace with newval. |
| newval | An expression that resolves to a string. The data to be inserted. |
Description
The FIELDSTORE replaces one or more delimited substrings in string with a specified newval, then returns the resulting string. The source string remains unchanged. FIELDSTORE adds and removes delimiters as needed.
-
To replace a delimited substring with another substring, specify a count that corresponds to an existing delimited string and multiple=1.
-
To replace more than one delimited substrings with a single delimited substring, specify a count that corresponds to an existing delimited string and a multiple greater than one. Both the replaced substrings and their delimiters are removed.
-
To append a delimited substring to the end of string, specify a count greater than the number of existing delimited strings. FIELDSTORE adds the appropriate number of delimiter characters, if necessary, before the newval substring.
-
To prepend a delimited substring to the beginning of string, specify a count=1 and multiple=0. FIELDSTORE appends a delimiter character and the newval substring.
-
To delete a delimited substring, specify a count that corresponds to an existing delimited string and specify newval as the empty string.
If delimiter is not found in string, and count is 1, 0, or the null string, newval replaces string and is returned with no delimiters. If delimiter is not found in string, and count is > 1, the specified delimiter and newval are appended to string. The number of delimiters appended being count minus 1.
Examples
The following example uses the FIELDSTORE function to return a string that replaces the first delimited substring in the string:
cities="New York^London^Chicago^Boston^Los Angeles"
PRINT FIELDSTORE(cities,"^",1,1,"Providence")
! Returns: "Providence^London^Chicago^Boston^Los Angeles"
The following example uses the FIELDSTORE function to return a string that replaces the second Value Mark delimited substring in the dynamic array:
cities="New York":@VM:"London":@VM:"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT cities
! Returns: "New YorkýLondonýChicagoýBostonýLos Angeles"
PRINT FIELDSTORE(cities,CHAR(253),2,1,"Providence")
! Returns: "New YorkýProvidenceýChicagoýBostonýLos Angeles"
The following example uses the FIELDSTORE function to replace the second Value Mark delimited substring and the next two substrings in a dynamic array:
cities="New York":@VM:"London":@VM:"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT cities
! Returns: "New YorkýLondonýChicagoýBostonýLos Angeles"
PRINT FIELDSTORE(cities,CHAR(253),2,3,"Providence")
! Returns: "New YorkýProvidenceýLos Angeles"
