Function AIns() | Xbase++ | Alaska Software

Inserts an element into an array and optionally assigns a value to it.

AIns( <aArray>, <nElement> [,<Expression>] ) --> aArray

<aArray> is the array into which an element is inserted.

<nElement> is a numeric value indicating the position at which the element is inserted.

<Expression> is an optional expression whose value is assigned to the array element designated by <nElement>. If <Expression> is missing, the value NIL is assigned to the element.

Ains() returns the reference to <aArray>.

The array function AIns() inserts the value <Expression> at the position <nElement> within the array. All array elements, starting with this position, are shifted down one element and the content of the last element is lost. The number of array elements Len(<aArray>)remains unchanged by AIns().

To avoid losing the value in the last element the function AAdd() can be used. AAdd() adds an element to the end of the array prior to the insertion.

Insert an element into an array using AIns()

// The example shows how a new element can be 
// inserted into an array without losing the last 
// element. 

PROCEDURE Main 
   LOCAL aArray 

   aArray := { 1, 2, 4, 5, 6 } 

   AAdd( aArray, NIL )      // aArray is: { 1, 2, 4, 5, 6, NIL } 

   AIns( aArray, 3 )        // aArray is: { 1, 2, NIL, 4, 5, 6 } 

   aArray[3] := 3           // aArray is: { 1, 2, 3, 4, 5, 6 } 

   AIns( aArray, 3, "A")    // aArray is: { 1, 2, "A", 3, 4, 5 } 

RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function AIns() Foundation