insert( )

Topic group Related topics Example

Inserts an element with the value false into a one-dimensional array, or inserts a row or column of elements with the value false into a two-dimensional array. Returns 1 if successful; generates an error if unsuccessful. The dimensions of the array do not change, so the element(s) at the end of the array will be lost.

Syntax

<oRef>.insert(<position expN> [, <row/column expN>])

<oRef>

A reference to a one- or two-dimensional array in which you want to insert data.

<position expN>

When <oRef> is a one-dimensional array, <position expN> specifies the number of the element in which you want to insert a false value.

When <oRef> is a two-dimensional array, <position expN> specifies the number of a row or column in which you want to insert false values. The second argument (discussed in the next paragraph) specifies whether <position expN> is a row or a column.

<row/column expN>

Either 1 or 2. If you omit this argument or specify 1, a row is inserted into a two-dimensional array. If you specify 2, a column is inserted. dBASE Plus generates an error if you use <row/column expN> with a one-dimensional array.

Property of

Array

Description

Use insert( ) to insert elements in an array. insert( ) does the following:

Inserts an element in a one-dimensional array, or inserts a row or column in a two-dimensional array

Moves all remaining elements toward the end of the array (down if a row is inserted, to the right if an element or column is inserted)

Stores false values in the newly created position(s)

Because the dimensions of the array are not changed, the element(s) at the end of the array—the last element for a one-dimensional array or the last row or column for a two-dimensional array—are lost. If you don’t want to lose the data, use grow( ) to increase the size of the array before using insert( ).

One-dimensional arrays

When you call insert( ) for a one-dimensional array, the logical value false is inserted into the position of the specified element. The remaining element(s) are moved one place toward the end of the array. The element that had been in the last position is lost.

For example, if you define a one-dimensional array with:

aAlpha = {"A", "B", "C"}

the resulting array has one row and can be illustrated as follows:

A B C

Issuing aAlpha.insert(2) inserts false into element number 2, moves the "B" that was in aAlpha[2] to aAlpha[3], and loses the "C" that was in aAlpha[3] so that the array now contains these values:

A false B

Two-dimensional arrays

When you call insert( ) for a two-dimensional array, a logical value false is inserted into the position of each element in the specified row or column. The elements in the remaining columns or rows are moved one place toward the end of the array. The elements that had been in the last row or column are lost.

For example, suppose you define a two-dimensional array and store letters to the array. The following illustration shows how the array is changed by aAlpha.insert(2,2).