ARRAY DELETE statement

Purpose

Delete a single item from a given array.

Syntax

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

Remarks

ARRAY DELETE deletes the data stored at the nominated element in array, an n-dimensional array.  You can specify the index of the element which is to have its data deleted, how many elements (count) are to be automatically shifted down by one position, and what data value to give the last element after the rest of the elements have been shifted (expression).

All of these parameters are optional.  If index is not specified, the data stored in the element at the beginning of the array is deleted.  If expression is not present, the last element that the data is shifted out of 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 eliminate the element, only count elements will be shifted.

By default, ARRAY DELETE throws away the data at the element index of array, shifting the data in the appropriate portion of the array to cover the old element:

DIM A(1 TO 4) AS LONG

ARRAY DELETE A(2), 17&

makes A(2)=A(3), A(3)=A(4), and A(4)=17.  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 DELETE A(2) FOR 2, 17&

makes A(2)=A(3) and A(3)=17 because you told it to shift only 2 elements.  The original values of A(4) and A(1) remain in place.

DELETE 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 element data from one dimension into another dimension, thus preserving the organization of the array.  For example:

DIM A(0 TO 1,0 TO 1) AS INTEGER

A(0,0)=0

A(1,0)=100

A(0,1)=200

A(1,1)=300

ARRAY DELETE A(0,0) FOR 2, 17%

makes A(0,0)=100 and A(1,0)=17.  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 DELETE A(0,0), 17%

makes A(0,0)=100, A(1,0)=200, A(0,1)=300, and A(1,1)=17.  The original value of A(0,0) is lost.

Restrictions

ARRAY DELETE cannot be used on arrays within UDT structures.  However, ARRAY DELETE can be used with arrays of UDT structures - simply treat them as if they were an array of fixed-length strings.

To use ARRAY DELETE 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 DELETE 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 DELETE Temp(5), "string"

ERASE Temp()

See also

ARRAY ASSIGN, ARRAY INSERT, ARRAY SCAN, ARRAY SORT, DIM, LBOUND, REDIM, UBOUND, Array Data Types

Example

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

DIM A(0 TO 3) AS CUX

A(0)=0

A(1)=1

A(2)=2

A(3)=3

ARRAY DELETE A(2), 2.5@@

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

DIM A(0 TO 2) AS EXT
A(0)=1
A(1)=2
A(2)=3
ARRAY DELETE A()