Logo

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

AINS(), ADEL()

These two functions add and remove elements from an array, respectively. Their names, which imply insert and delete, are somewhat misleading because they don’t affect the size of the array, only its contents. AINS() pushes extra data out the end of the array, while ADEL() leaves empty cells at the end. What makes these functions so useful is that they adjust the elements that follow the insertion or deletion point. That is, when you AINS(), the items from the insertion point on get pushed toward the end of the array. With ADEL(), items from the deletion point on get moved toward the beginning of the array.

Usage

nReturn = AINS( ArrayName, nPos [, nRowOrCol ] )

Parameter

Value

Meaning

ArrayName

Array Name

The array to have an element, row or column inserted. If ArrayName is one-dimensional, a single element is inserted. If ArrayName is two-dimensional, either a row or column is inserted. The newly inserted element or elements are initialized to .F.

nPos

Numeric

The position at which the new element, row or column is inserted. All items from that position to the end of the array get pushed further out into the array. The data from the last element, row or column is lost. For a one-dimensional array, nPos is the element number. (See "DBF, FPT, CDX, DBC—Hike!" for an explanation of element numbers.) For a two-dimensional array, nPos is the row or column number where insertion takes place.

nRowOrCol

2

Insert a column into a two-dimensional array. This is the only documented third parameter, but see the next entry.

Omitted or 1, 0 or negative number

Insert an element into a one-dimensional array or a row into a two-dimensional array. The documentation says 2 is the only third parameter you can pass, but passing a number less than or equal to 1 is identical to omitting the parameter.

As far as we can tell, AINS() always returns 1 except when an error occurs; then it doesn’t return anything.

Example

DIMENSION aTest[3]
aTest[1] = 1
aTest[2] = 2
aTest[3] = 3
? AINS(aTest, 2)  && Insert a new 2nd element - returns 1
? aTest[1]        && 1
? aTest[2]        && .F.
? aTest[3]        && 2

DIMENSION a2DTest[3,2]
FOR nCnt = 1 TO 6
   a2DTest[nCnt] = nCnt
ENDFOR
? AINS(a2DTest, 2) && Insert a new 2nd Row
DISPLAY MEMORY     && Shows 1 and 2 in first row, .F. in both
                   && elements of 2nd row and 3 and 4 in third
                   && row

* reinitialize
FOR nCnt=1 TO 6
    a2Dtest[nCnt] = nCnt
ENDFOR
? AINS(a2DTest, 1, 2)  && Insert a new 1st Column
DISPLAY MEMORY         && Shows first column as all .F.,
                       && 1, 3, 5 in second column

Because AINS() throws data away, you’ll typically want to redimension the array before using it. Add the new element, row or column, then insert it in the right place.

* add a new third row to an existing array
DIMENSION aArray[ ALEN(aArray, 1) + 1, ALEN(aArray, 2) ]
=AINS(aArray, 3)

Unfortunately, adding a new column this way isn’t so easy. AINS() handles column insertion neatly, pushing the items in the last column out into the bit bucket. But redimensioning an array to have an additional column isn’t as well behaved. Data stays in the element with the same element number, which is not the same (row,column) position. Take a look at the aColCopy() function under ACOPY() to see how to work around this problem.

Usage

nReturn = ADEL( ArrayName, nPos [, nRowOrCol ] )

Parameter

Value

Meaning

ArrayName

Array Name

The array to have an element, row or column deleted. If ArrayName is one-dimensional, a single element is deleted. If ArrayName is two-dimensional, either a row or column is deleted.

nPos

Numeric

The position from which the new element, row or column is deleted. All items from that position to the end of the array get moved forward to fill the beginning of the array. The last element, row or column is filled with .F. For a one-dimensional array, nPos is the element number. (See "DBC, DBF,FPT—Hike!" for an explanation of element numbers.) For a two-dimensional array, nPos is the row or column number.

nRowOrCol

2

Delete a column in a two-dimensional array. This is the only documented third parameter, but see the next entry.

Omitted or 1, 0 or negative number

Delete an element in a one-dimensional array or a row in a two-dimensional array. The documentation says 2 is the only third parameter you can pass, but passing a number less than or equal to 1 is identical to omitting the parameter.

As with AINS(), it appears that ADEL() always returns 1 unless it fails.

Example

DIMENSION aTest[3]
aTest[1] = 1
aTest[2] = 2
aTest[3] = 3
? ADEL(aTest, 2)  && delete 2nd element
? aTest[1]        && 1
? aTest[2]        && 3
? aTest[3]        && .F.

DIMENSION a2DTest[3,2]
FOR nCnt = 1 TO 6
    a2Dtest[nCnt] = nCnt
ENDFOR
? ADEL(a2DTest,2)   && delete 2nd row
DISPLAY MEMORY      && shows 1 and 2 in first row,
                    && 5 and 6 in second row, and .F. in 3rd row

* reinitialize
FOR nCnt=1 TO 6
    a2Dtest[nCnt] = nCnt
ENDFOR
? ADEL(a2DTest,1,2)  && delete 1st column
DISPLAY MEMORY       && shows 2, 4, 6 in first column,
                     && .F. in 2nd column

With ADEL(), you’ll usually want to redimension the array afterward. Remove the data, leaving empty cells at the end, then redimension to get rid of the empties.

* remove the 4th element of array and resize
=ADEL(aArray, 4)
DIMENSION aArray[ ALEN(aArray) - 1 ]

As with AINS(), redimensioning following deletion of a column is messy. You have to move data around to avoid losing it or having it in the wrong place.

See Also

AElement(), ALen(), Array Manipulation, ASubscript(), Dimension