AADD()
 Add a new element to the end of an array
------------------------------------------------------------------------------
 Syntax

     AADD(<aTarget>, <expValue>) --> Value

 Arguments

     <aTarget> is the array to which a new element is to be added.

     <expValue> is the value assigned to the new element.

 Returns

     AADD() evaluates <expValue> and returns its value.  If <expValue> is not
     specified, AADD() returns NIL.

 Description

     AADD() is an array function that increases the actual length of the
     target array by one.  The newly created array element is assigned the
     value specified by <expValue>.

     AADD() is used to dynamically grow an array.  It is useful for building
     dynamic lists or queues.  A good example of this is the GetList array
     used by the Get system to hold Get objects.  After a READ or CLEAR GETS,
     GetList becomes an empty array.  Each time you execute an @...GET
     command, the Get system uses AADD() to add a new element to the end of
     the GetList array, and then assigns a new Get object to the new element.

     AADD() is similar to ASIZE() but only adds one element at a time;
     ASIZE() can grow or shrink an array to a specified size.  AADD(),
     however, has the advantage that it can assign a value to the new
     element, while ASIZE() cannot.  AADD() may also seem similar to AINS(),
     but they are different:  AINS() moves elements within an array, but it
     does not change the array's length.

     Note:  If <expValue> is another array, the new element in the target
     array will contain a reference to the array specified by <expValue>.

 Examples

     .  These examples demonstrate the effects of multiple invocations
        of AADD() to an array:

        aArray := {}                  // Result: aArray is an empty array
        AADD(aArray, 5)               // Result: aArray is { 5 }
        AADD(aArray, 10)              // Result: aArray is { 5, 10 }
        AADD(aArray, { 12, 10 })      // Result: aArray is
                                      // { 5, 10, { 12, 10 } }

 Files   Library is CLIPPER.LIB.