|
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)=3. A(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() |