Click above to get retro games delivered to your door ever month!

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

 Syntax

    A_ADD(   @<aTarget>,
             [<nDimension>] )   ->    lSuccess

 Arguments

    <aTarget> is the array to which you are adding new element(s).
    It must be passed-by-reference.  A_ADD() cannot add elements to
    a binary (logical) type array.

    <nDimension> is the dimension that will be increased by one.
    The default is the last dimension in the list of dimensions.

 Returns

    A_ADD() returns a (.T.) if successful, otherwise, it returns a
    (.F.).

 Description

    A_ADD() works differently than Clipper's AADD() function. This is
    because FlexFile arrays are matrices and cannot have "ragged"
    lengths in any dimension.

    So, A_ADD() adds one element in a one dimensional array, one row
    in a two dimensional array, one page in a three dimensional array,
    and so forth.

    For example, imagine a two dimensional array containing students
    grades. Along one axis are the students; along the other are the
    exams. When the semester begins the professor may not know how
    many exams there are going to be (or how to handle a new student).
    If you look at both of these situations you will understand
    FlexFile's A_ADD().

    Lets assume that the professor begins with 20 students and plans
    the course to consist of 5 exams:

    students = 20
    exams = 5
    array = A_DECLARE( 'I', students, exams )


    Later in the course he needs to add a new student.

    A_ADD( @array, 1 )

    The second parameter is one to tell A_ADD that we are adding a
    row of exams for a new student. The value is one because when
    we declared the array the students were the first array
    index.

    Later the professor needs to add another exam for all students:

    A_ADD( @array, 2 )


 Examples

    // Declare a two dimensional unsigned (T)iny integer array
    LOCAL rows, cols

    rows = 10
    cols = 20
    aTiny = A_DECLARE( "UT", rows, cols )

    // Increase the columns to 21.
    A_ADD( @aTiny, 2 )