AINS()
 Insert a NIL element into an array
------------------------------------------------------------------------------
 Syntax

     AINS(<aTarget>, <nPosition>) --> aTarget

 Arguments

     <aTarget> is the array into which a new element will be inserted.

     <nPosition> is the position at which the new element will be
     inserted.

 Returns

     AINS() returns a reference to the target array, <aTarget>.

 Description

     AINS() is an array function that inserts a new element into a specified
     array.  The newly inserted element is NIL data type until a new value is
     assigned to it.  After the insertion, the last element in the array is
     discarded, and all elements after the new element are shifted down one
     position.

     Warning!  AINS() must be used carefully with multidimensional
     arrays.  Multidimensional arrays in CA-Clipper are implemented by
     nesting arrays within other arrays.  Using AINS() in a multidimensional
     array discards the last element in the specified target array which, if
     it is an array element, will cause one or more dimensions to be lost.
     To insert a new dimension into an array, first add a new element to the
     end of the array using AADD() or ASIZE() before using AINS().

 Examples

     .  This example demonstrates the effect of using AINS() on an
        array:

        LOCAL aArray
        aArray := { 1, 2, 3 }      // Result: aArray is
                                   // now { 1, 2, 3 }
        AINS(aArray, 2)            // Result: aArray is
                                   // now { 1, NIL, 2 }

 Files   Library is CLIPPER.LIB.