Function AIns() Foundation

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

Syntax
AIns( <aArray>, <nElement> [,<Expression>] ) --> aArray
Parameters
<aArray>
<aArray> is the array into which an element is inserted.
<nElement>
<nElement> is a numeric value indicating the position at which the element is inserted.
<Expression>
<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.
Return

Ains() returns the reference to <aArray>.

Description

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.

Examples
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 
Feedback

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.