ARRAY INSERT statement

Purpose

Insert a single item into a given array.

Syntax

ARRAY INSERT array([index]) [FOR count] [, expression]

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 expression 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

mkes 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.  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

...

DIM Sales AS SalesType

...

DIM Temp(1 TO 20) AS STRING * 20 AT VARPTR(Sales.Partnumber(1))

ARRAY INSERT Temp(5), "string"

ERASE Temp()

See also

ARRAY ASSIGN, ARRAY DELETE, ARRAY SCAN, ARRAY SORT, DIM, LBOUND, REDIM, UBOUND

Example

Makes A(3)=2.5 and A(4)=3A(0), A(1), and A(2) remain in place:

DIM A(0 TO 4) AS DOUBLE

A(0)=0

A(1)=1

A(2)=2

A(3)=3

ARRAY INSERT A(3), 2.5#

Makes  A(0)=0, A(1)=1, and A(2)=2.  The original value of A(2) is lost:

DIM A(0 TO 2) AS QUAD

A(0)=1

A(1)=2

A(2)=3

ARRAY INSERT A()