prg_list_iterator_elem_find()
Abstract
Finds an element in a list and returns a pointer to it.
Syntax
prg_list_iterator_elem_find (list_iter_ptr, test_func, elem_ptr, low_bound_pos_ptr, high_bound_pos_ptr)
| Argument | Type | Description |
|---|---|---|
list_iter_ptr |
PrgT_List_Iterator * |
The list iterator associated with the list to search. |
test_func |
PrgT_List_Compare_Proc |
Procedure used to match elem_ptr to a list element. |
elem_ptr |
const void* |
Element to be matched against the list elements. |
low_bound_pos_ptr |
int * |
Area to be filled with a pointer to a list element. See Details. |
high_bound_pos_ptr |
int * |
Area to be filled with a pointer to a list element. See Details. |
Return Type
VosT_Address
Address of the first matching element, or PRGC_NIL.
Header
prg_list_funcs.h
Details
The test_func procedure is applied to a list element and elem_ptr to determine if a match is found. The following table shows the values returned and filled into low_bound_pos_ptr and high_bound_pos_ptr for different conditions.
| Return Value | low_bound_pos_ptr | high_bound_pos_ptr | |
|---|---|---|---|
| Match found and… | |||
| …list is sorted | address of matching element with lowest index | position of matching element with lowest index | position of matching element with highest index |
| …list is unsorted | same as low_bound_pos_ptr |
||
| No match found and… | |||
| …list is sorted | PRGC_NIL |
position of element next-lowest to high_bound_pos_ptr,or –1 if none |
position at which to insert elem_ptr to maintain a sorted list |
| …list is unsorted | –1 | –1 |
The prototype for test_func is given in PrgT_List_Compare_Proc.
WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.