Inserts data in a dynamic array.
||An expression that resolves to the name of a dynamic array.
||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.
||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.
||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.
||The data to be inserted. An expression that resolves to a string.
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
, 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
arguments are optional and can be omitted.
To insert a value at the beginning of a dynarray
to 1 or 0. To insert a value at the end of a dynarray
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
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"
! Returns: "New YorkýProvidenceýLondonýChicagoýBostonýLos Angeles"
UniData systems differ in how they handle f
, and s
arguments set to 0. The $OPTIONS ATTR.0IS1 (zero is one) provides support for this UniData feature. UniData systems ignore v
arguments that are set to a negative number.
© 1997-2019 InterSystems Corporation, Cambridge, MA