The INSERTAT statement immediately alters the space allocated to an array variable by inserting exactly the number of elements specified at the position specified. As the name implies, INSERTAT can only increase the size of the array. To decrease the size of the array, refer to realloc or removeat.

INSERTAT may only be used on variables that have been declared as arrays. If INSERTAT is supplied with a variable that is not declared as an array the compiler will generate an error.

If INSERTAT is given an insertion position beyond the current size of the array, it will emulate the functionality of realloc. In other words, N elements will be added to the end of the array, the array will NOT be resized to accomodate the invalid position.

Refer to realloc for more information regarding resizing arrays.

Parameters

Varname

The variable, declared as an array, to resize.

Position

The zero based position to begin the insertion. For example, providing integer 0 for this parameter will insert elements at the start of the array. Providing integer 1 will insert elements after the first array element, etc.

Count

The number of elements to insert.

Return Value

No return value.

Example Code

// Declare an array with 5 elements
int test[5];
for(int ic = 0; ic < getalloc(test); ic++)
{
    // Set and print an example value
    test[ic] = ic * 10;
    print test[ic];
}

print "Resizing array...";

// Insert 1 element at element #3 (zero based, therefore #3 is [2])
insertat(test, 2, 1);

test[2] = 9999;

for(ic = 0; ic < getalloc(test); ic++)
{
    // Print the array contents with the extra insertion
    print test[ic];
}