$FUNCNAME$
  AINS()
$CATEGORY$
  Array, Object
$SUMMARY$
   Insert a NIL element into an array
$LANG_RU$
       NIL  .
$SYNTAX$
     AINS(<aTarget>, <nPosition>) --> aTarget
$LANG_RU$
     AINS(< >,< >) -->  
$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.
$LANG_RU$
     < > - ,     .
     < > - ,     .
$RETURNS$
     AINS() returns a reference to the target array, <aTarget>.
$LANG_RU$
     AINS()     < >.
$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 xClipper 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().
$LANG_RU$
     AINS() -   ,     
      .      NIL,  
        .     
       ,        
      .

     :
          AINS()  
      .    xClipper  
         .    AINS()
            
     ,        .  
              
      ,   AADD()  ASIZE()  
     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 }
$LANG_RU$
            AINS() 
        :

       LOCAL aArray := { 1, 2, 3 }     // : { 1, 2, 3 }
       AINS(aArray, 2)                 // : { 1, NIL, 2 }
$SEEALSO$
  AADD(),ACOPY(),ADEL(),AEVAL(),AFILL(),ASIZE(),
$END$
