TutPtrAryInsertItemAtIndex

Name

TutPtrAryInsertItemAtIndex — insert item in a pointer array at the specified index

Synopsis

T_BOOL TutPtrAryInsertItemAtIndex(ptr_ary, new_item, index) 
T_PTR_ARY ptr_ary; 
T_PTR new_item; 
T_INT4 index; 

Arguments

ptr_ary — pointer array where new item is inserted

new_item — item to be inserted

index — index at which item is inserted

Return Values

TRUE if the operation is a success, FALSE otherwise.

Diagnostics

None

Description

TutPtrAryInsertItemAtIndex inserts a new item in the pointer array at the specified index. The items stored in the rest of the array shifts to accommodate the insertion. The index has a range from zero to the total number of items in the array minus one. Specifying an index outside of those boundaries causes the insertion to fail, and causes TutPtrAryInsertItemAtIndex to return FALSE. Arrays with gaps are not permitted.

TutPtrAryInsertItemAtIndex calls the pointer array change callbacks with the reason T_PA_ITEM_INSERTED.

Caution

None

See Also

TutPtrAryAppend, TutPtrAryReplaceItemAtIndex

Examples

This example inserts a new item in the pointer array:

T_PTR_ARY ptr_ary; 
T_INT4 i, *int_ptr; 
 
/* create the pointer array with initial size of 30 */ 
 
ptr_ary = TutPtrAryCreate(30); 
/* fill it up with 25 entries */ 
for (i = 0; i < 25; i++) { 
  /* allocate the space for the next element */ 
  T_MALLOC(int_ptr, sizeof(T_INT4), T_INT4 *); 
  *int_ptr = i; 
  /* append the item to the array, ignore the index */ 
  TutPtrAryAppend(ptr_ary, int_ptr, NULL); 
}  
 
/* now create and insert a new item at index 13 */ 
T_MALLOC(int_ptr, sizeof(T_INT4), T_INT4 *); 
*int_ptr = 169; 
TutPtrAryInsertItemAtIndex(ptr_ary, int_ptr, 13); 
 
/* after the call to TutPtrAryInsertItemAtIndex, the array will have 
   the following elements:  
    0 1 2 3 4 5 6 7 8 9 10 11 12 169 13 14 ... 24  
 
  TutPtrAryGetItemCount returns 26 as the number of items in 
  the array */