INS
Synopsis
INS expression BEFORE dynarray <f[,v[,s]]>
Arguments
| expression | The data to be inserted. |
| dynarray | The name of a valid dynamic array. If the dynamic array does not exist, INS creates it. |
| f | An integer specifying the Field level of the dynamic array in which to insert the data. Fields are counted from 1. |
| v | Optional — 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 integer specifying the Subvalue level of the dynamic array in which to insert the data. Subvalues are counted from 1 within a Value. |
Description
The INS command inserts a data value at the specified dynamic array location. 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 INS statement does not overwrite; if there already was a third value, the insert increments its location to the fourth value. INS adds multiple delimiter characters, when needed, to place the data value at the specified location.
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, a non-numeric value, or an undefined variable is equivalent to setting it to 1.
Both the INS command and the INSERT function insert a value into a dynamic array. The INS command changes the value of the supplied dynarray. The INSERT function returns a dynamic array containing the insert; it does not change the value of the supplied dynarray.
Examples
The following example uses the INS command 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"
INS "Providence" BEFORE cities <1,2>
PRINT cities
! Returns: "New YorkýProvidenceýLondonýChicagoýBostonýLos Angeles"
