INSERT
Synopsis
INSERT(dynarray,f[,v[,s]];expression)
Arguments
dynarray | An expression that resolves to the name of a dynamic array. |
f | An expression that resolves to an integer specifying the Field level of the dynamic array in which to insert the data. Fields are counted from 1. |
v | Optional — An expression that resolves to an integer specifying the Value level of the dynamic array in which to insert 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 in which to insert the data. Subvalues are counted from 1 within a Value. |
;expression | The data to be inserted. An expression that resolves to a string. |
Description
The INSERT function inserts a data value at the specified dynamic array location, then returns the full dynamic array including this insertion. Which element to insert is specified by the f, v, and s integers. For example, if f=2 and v=3, this means insert the new data value as the third value in the second field. The INSERT function does not overwrite; if there already was a third value, the insert increments its location to the fourth value. INSERT adds multiple delimiter characters, when needed, to place the data value at the specified location.
Note that a semicolon (;) is used before expression as an argument separator. This is because the v and s arguments are optional and can be omitted.
To insert a value at the beginning of a dynarray set f to 1 or 0. To insert a value at the end of a dynarray set f to -1. 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.
Both the INSERT function and the INS command insert a value into a dynamic array. The INSERT function returns a dynamic array containing the insert; it does not change the value of the supplied dynarray. The INS command changes the value of the supplied dynarray.
Examples
The following example uses the INSERT function to insert the second value in the first field of a dynamic array:
cities="New York":@VM:"London":@VM:"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT INSERT(cities,1,2;"Providence")
! Returns: "New YorkýProvidenceýLondonýChicagoýBostonýLos Angeles"
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.
See Also
-
INS statement
-
COUNTS function
-
DELETE function
-
EXTRACT function
-
FIELDSTORE function