op_prg_list_elem_find()
Abstract
Finds an element in a list and returns a pointer to it.
Note: This KP is a macro call included for backward compatibility only. Use prg_list_elem_find() in new code.
Syntax
op_prg_list_elem_find (list_ptr, test_func, elem_ptr, low_bound_pos_ptr, high_bound_pos_ptr)
| Argument | Type | Description |
|---|---|---|
list_ptr |
List* |
pointer to the list-of-interest [A pointer to a list can be obtained from several KPs: an empty list can be originally obtained from op_prg_list_create(), a list representing the contents of a file can be obtained from op_prg_gdf_read(), or a list can be allocated by user code, and initialized via op_prg_list_init().]. |
test_func |
List_Compare_Proc |
procedure called to determine if an element matches the search criteria (see Details for prototype) |
elem_ptr |
void* |
element against which other elements in the list are compared |
low_bound_pos_ptr |
int* |
Area to be filled with a pointer to a list element. See Table 13-1 in Details. |
high_bound_pos_ptr |
int* |
Area to be filled with a pointer to a list element. See Table 13-1 in Details. |
Return Type
void*
Pointer to the first matching element found in the specified list, or OPC_NIL.
Example
/* Check to see if the list already contains an element */
/* for this application. */
found_info = op_prg_list_elem_find (redirect_lptr, redirect_list_compare_proc,
redirect_info, &low_index, &high_index);
....
int
redirect_list_compare_proc (const StbT_Redirect_Info* element1,
const StbT_Redirect_Info* element2)
{
if (element1->application == element2->application)
{
FRET (0);
}
else if (element1->application < element2->application)
{
FRET (1);
}
else
{
FRET (-1);
}
}
Details
The source list specified by list_ptr must already be sorted (using test_func) before this function is called. There are two ways to sort the list in this manner:
- call op_prg_list_sort() with the same comparison procedure
- add all items to the list with op_prg_list_insert_sorted()
The test function is prototyped as follows:
int
List_Compare_Proc (void* element1, void* element2)
This callback should accept two arguments that are both pointers to the type of data structure or simple data type elements stored in the list-of-interest. The callback should return one of the following values to indicate the precedence relationship between the two elements:
- 1 if elem1 should be closer to the list head than elem2
- 0 if elem1 and elem2 are equal in rank
- -1 if elem2 should be closer to the list head than elem1
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 is 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 is found and… | …list is sorted | OPC_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 |
Note: This KP is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.
Purpose
To search for and return a particular element in a list, if the element’s position in the list is not known.
Errors
- Program Abort: Segmentation violation. (due to an invalid list pointer or malformed list)
Reference
- use op_prg_list_insert() to insert an element into a list
- use op_prg_list_insert_sorted() to insert an element into a sorted list