Higher Level Array Allocation

In addition to the basic memory allocation macros described previously, a set of useful macros for dealing with arrays of dynamically changing size are provided:

    SET_ARRAY_SIZE( array, previous_n_elems, new_n_elems,
                    chunk_size )

This macro increases or decreases the size of an array, by specifying the number of elements previously allocated to the array (starts out at zero). The chunk_size argument defines the size of the memory chunks which are allocated. For instance, if chunk_size is 100, then this macro will only reallocate the array if the size change crosses to a different multiple of 100, thus avoiding memory allocation every time it is called. This specification of the granularity of the memory allocation must be consistently specified; if this macro is called with a given variable and chunk size, then subsequent calls to this macro with the same variable must specify the same chunk size. Note also that the number passed in as new_n_elems must be passed in as previous_n_elems on the next call to this macro.

    ADD_ELEMENT_TO_ARRAY( array, n_elems,
                          elem_to_add, chunk_size )

Adds the argument elem_to_add to the array at the n_elems'th index, then increments n_elems. The argument chunk_size specifies the granularity of memory allocation.

    DELETE_ELEMENT_FROM_ARRAY( array, n_elems, index_to_remove,
                               chunk_size )

Deletes the index_to_remove'th element from the array, decreasing the number of elements in the array (n_elems) and decreasing the memory allocation, if crossing a multiple of chunk_size. Again, chunk_size must be specified the same for all invocations of the previous three macros involving a given pointer.

    ADD_ELEMENT_TO_ARRAY_WITH_SIZE( array, n_alloced, n_elems,
                                    elem_to_add, chunk_size )

Adds an element (elem_to_add) to the array, incrementing n_elems. If necessary, the memory is increased by the amount specified in chunk_size and the n_alloced variable is incremented by this amount. The usage of this differs from the use of ADD_ELEMENT_TO_ARRAY in that the number of elements (n_elems) can be decreased arbitrarily, without causing memory to be deallocated.