REPLACE
Synopsis
REPLACE(dynarray,f[,v[,s]];replacement)
Arguments
| dynarray | An expression that resolves to a dynamic array. |
| f | An expression that resolves to an integer specifying the Field level of the dynamic array from which to access the data. Fields are counted from 1. |
| v | Optional — An expression that resolves to an integer specifying the Value level of the dynamic array from which to access the data. Values are counted from 1 within a Field. |
| s | Optional — An expression that resolves to an integer specifying the Subvalue level of the dynamic array from which to access the data. Subvalues are counted from 1 within a Value. |
| replacement | An expression that resolves to a data value used to replace the element data value specified by f, v, and s. Note the semicolon (;) that precedes replacement; if f, v, and s are all specified, you can precede replacement with a comma, otherwise you must use a semicolon. |
Description
The REPLACE function replaces the data value in one element of a dynamic array with a new value. Which element to replace is specified by the f, v, and s integers. For example, if f=2 and v=3, this means replace the third value from the second field. If f=2 and v is not specified, this means to replace the entire second field.
If f, v, or s is higher than the current number of elements at that location, REPLACE appends the replacement value with the appropriate number of level delimiter characters.
Note that a semicolon (;) is used before replacement as an argument separator. This is because the v and s arguments are optional and can be omitted.
If replacement is the null string, REPLACE removes the current data value (replaces it with a null string), but does not remove the level delimiter character.
If lower level delimiters exist in dynarray, setting an upper level to 0, the null string, or a non-numeric value is equivalent to setting it to 1.
If lower level delimiters do not exist in dynarray, setting this nonexistent lower level to 1, 0, the null string, or a non-numeric value has no effect on the data value in the level above it.
You can also use the <> operator to replace an element value in a dynamic array. For further details, see the Dynamic Arrays page of this manual.
Examples
The following example replaces the second value from the first field of a dynamic array:
cities="New York":@VM:"London":@VM:
"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT REPLACE(cities,1,2;"Minneapolis")
The following example replaces the second value with an empty string:
cities="New York":@VM:"London":@VM:
"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT REPLACE(cities,1,2,0,"")
Emulation
UniData systems differ in how they handle f, v, and s arguments set to 0. The $OPTIONS ATTR.0IS1 (“zero is one”) provides support for this UniData feature. UniData systems ignore v and s arguments that are set to a negative number.
