xHarbour Reference Documentation > Function Reference

AIns()

Inserts an element into an array.

Syntax

AIns( <aArray>, <nElement>, [<xValue>], [<lGrow>] ) --> aArray

Arguments

<aArray>

A variable holding the array to insert an element into.

<nElement>

This is a numeric expression indicating the ordinal position where to insert the new array element. It must be in the range between 1 and Len(<aArray>).

<xValue>

A value of arbitrary data type to assign to the new array element. It defaults to NIL.

<lGrow>

Optionally, a logical value can be specified. If .T. (true) is passed, the length of the array is enlarged by one element. The default value is .F. (false) leaving the number of elements in <aArray> unchanged.

Return

The function returns a reference to <aArray>.

Description

The array function AIns() inserts a new element at position <nElement> into the array <aArray>. All subsequent elements are shifted down by one position so that the last element is lost when the function returns. This default behaviour leaves the number of elements in the array unchanged.

The new array element is initialized with NIL, but can be assigned a value when parameter <xValue> is not NIL.

If the fourth parameter <lGrow> is specified as .T. (true), the function first adds a new element and then shifts all elements down, beginning at the specified position. This way, the last element is preserved and the number of elements is enlarged by one.

Info

See also:	AAdd(), ACopy(), ADel(), AEval(), AFill(), ASize()
Category:	Array functions
Source:	vm\arrayshb.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// This example demonstrates two results of inserting an
// array element

   PROCEDURE Main()
      LOCAL aArray := { "A", "B", "C" }

      AIns( aArray, 2 )

      ? Len( aArray )                    // result: 3
      ? aArray[1], aArray[2], aArray[3]  // result: A NIL B

      AIns( aArray, 2, "C", .T. )

      ? Len( aArray )                    // result: 4
      ? aArray[1], aArray[2], aArray[3], aArray[4]
                                         // result: A C NIL B
   RETURN