TutPtrAryCreate

Name

TutPtrAryCreate — create a pointer array

Synopsis

T_PTR_ARY TutPtrAryCreate(size) 
T_INT4 size; 

Arguments

size — initial size of the pointer array

Return Values

Returns a pointer to the new pointer array.

Diagnostics

None

Description

TutPtrAryCreate creates a new pointer array.

A pointer array is an opaque data structure that contains a zero-based array of pointers to values. The key features of the pointer array data structure are the automatic resizing of the array to provide the room for the next element, thus allowing an unlimited number of elements in the array, and the re-use of previously allocated storage to minimize system calls to allocate memory.

During the call to TutPtrAryCreate, the space for the pointer array data structure is allocated, and the pointer array of size is created. size is then used as an increment by which the size of the array increases every time the array gets filled up, and a new element needs to be inserted.

For example, if size is six, and the seventh element is added, the array size increases by six. After the addition the pointer array contains seven elements, but has enough memory allocated to hold twelve. The average speed of addition of an element depends on the total number of elements to be added and the initial size specified. By monitoring the array size during the program run and adjusting the initial size, it may be possible to optimize memory usage and speed of addition. The speed of access is independent of either the initial size or the total number of elements and is always a constant.

Caution

None

See Also

TutPtrAryDestroy, TutPtrAryClear

Examples

This example creates a new pointer array:

T_PTR_ARY ptr_ary; 
/* create the pointer array with initial size of 30 */ 
ptr_ary = TutPtrAryCreate(30);