TutPtrAryInsertBefore

TutPtrAryInsertBefore — insert a new item in a pointer array before the specified item

Synopsis

T_BOOL TutPtrAryInsertBefore(ptr_ary, index_item, new_item) 
T_PTR_ARY ptr_ary; 
T_PTR index_item; 
T_PTR new_item;

Arguments

Return Values

TRUE if the operation is a success, FALSE if index_item is not an element in the array, or if the ptr_ary is invalid.

Diagnostics

Description

TutPtrAryInsertBefore inserts the new item in the array before the first occurrence of the specified index item. index_item must be part of the array for the insertion to work. During this operation, the array may be resized as necessary to accommodate the new element.

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

Caution

See Also

Examples

T_PTR_ARY ptr_ary; 
T_INT4 i, *int_ptr, *mark_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); 
  if (i == 13) { 
    mark_ptr = int_ptr; 
  }  
}  
 
/* now create and insert a new item before the marked one */ 
T_MALLOC(int_ptr, sizeof(T_INT4), T_INT4 *); 
*int_ptr = 169; 
TutPtrAryInsertBefore(ptr_ary, mark_ptr, int_ptr); 
 
/ * after the call to TutPtrAryInsertBefore, 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 */