Remarks |
ARRAY INSERT inserts a single data item into *array*,
an *n*-dimensional array. You can specify the *index*
at which the new element data is to be inserted, how many elements (*count)*
are to* *be shifted up by one position to make room for the new element
data, and what data value to give the new element (*expression*).
All of these parameters are optional. If *index*
is not specified, the element data is inserted at the beginning of the
array If e*xpression* is not present, the new element will
contain zero if *array* is a numeric array, or an empty string if
*array* is a string array.
If a shift *count* is given, when shifting
the rest of the array to make way for the new element data, only *count*
elements will be shifted.
By default, ARRAY INSERT throws away the data in
last element of *array*, then shifts the appropriate portion of the
array to make way for the new element data:
DIM A(1 TO 4) AS LONG
ARRAY INSERT A(2), 17
makes *A(4)*=*A(3)*, *A(3)*=*A(2)*,
and *A(2)*=*17*. The original value of *A(4)* is
lost, while the original value of *A(1)* remains in place.
Use *count* to "protect" a portion of the array from the
shift:
DIM A(1 TO 4) AS LONG
ARRAY INSERT A(2) FOR 2, 17
makes *A(3)*=*A(2)* and *A(2)*=*17*
because you told it to shift only 2 elements. The original values
of *A(4)* and *A(1)* remain in place.
**INSERT**** with multi-dimensional arrays**
*count* can also
be used with a multi-dimensional
array (stored in linear column-major order; see ARRAY
SORT), to prevent shifting data from one dimension into another
dimension, and thus preserving the organization of the array. For
example:
DIM A(0 TO 1,0 TO 1) AS SINGLE
A(0,0)=0
A(1,0)=100
A(0,1)=200
A(1,1)=300
ARRAY INSERT A(0,0) FOR 2, 17
makes *A(0,0)*=*17* and *A(1,0)*=*0*.
The original values of *A(0,1)* and *A(1,1)* remain in place
since you told it to shift only 2 elements. Without *count*:
ARRAY INSERT A(0,0), 17
makes *A(0,0)*=*17*, *A(1,0)*=*0*,
*A(0,1)*=*100*, and *A(1,1)*=*200*. The original
value of *A(1,1)* is lost. |

Restrictions |
ARRAY INSERT cannot be used on arrays *within
*UDT structures or on an
array of Interfaces.
However, ARRAY INSERT can be used with arrays *of* UDT structures
- simply treat them as if they were an array of fixed-length strings.
To use ARRAY INSERT on an embedded UDT array, use
DIM..AT to dimension a regular array (of
the same type) directly "over the top" of the UDT array, and
use ARRAY INSERT on that array. For example:
TYPE SalesType
OrderNum AS LONG
PartNumber(1 TO 20) AS STRING * 20
END TYPE
[*statements*]
DIM Sales AS SalesType
[*statements*]
DIM Temp(1 TO 20) AS STRING * 20 AT VARPTR(Sales.Partnumber(1))
ARRAY INSERT Temp(5), "string"
ERASE Temp() |