op_prg_list_elem_find()
摘要
在列表中查找元素,并返回指向它的指针。
注意: 该内核过程是一个仅为向后兼容而保留的宏调用。新代码应使用 prg_list_elem_find()。
语法
op_prg_list_elem_find (list_ptr, test_func, elem_ptr, low_bound_pos_ptr, high_bound_pos_ptr)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
List* |
指向目标列表的指针 [列表指针可以从多个内核过程获得:空列表最初可由 op_prg_list_create() 获得,表示文件内容的列表可由 op_prg_gdf_read() 获得,或者列表可由用户代码分配并通过 op_prg_list_init() 初始化。]。 |
test_func |
List_Compare_Proc |
用于判断元素是否匹配搜索条件的过程(原型参见详情) |
elem_ptr |
void* |
列表中其他元素与之比较的元素 |
low_bound_pos_ptr |
int* |
将被填入列表元素指针的区域。参见详情中的表 13-1。 |
high_bound_pos_ptr |
int* |
将被填入列表元素指针的区域。参见详情中的表 13-1。 |
返回类型
void*
指向在指定列表中找到的第一个匹配元素的指针,或 OPC_NIL。
示例
/* 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);
}
}
详情
list_ptr 指定的源列表必须在调用此函数之前已经按 test_func 排好序。有两种方式可以以这种方式对列表排序:
- 使用相同的比较过程调用 op_prg_list_sort()
- 使用 op_prg_list_insert_sorted() 将所有项添加到列表
测试过程的原型如下:
int
List_Compare_Proc (void* element1, void* element2)
该回调应接受两个参数,二者均为存储在目标列表中的数据结构类型或简单数据类型元素的指针。回调应返回下列值之一,以指示两个元素之间的优先关系:
- 若 elem1 应比 elem2 更靠近列表头部,返回 1
- 若 elem1 与 elem2 等级相等,返回 0
- 若 elem2 应比 elem1 更靠近列表头部,返回 -1
test_func 过程被应用于列表元素和 elem_ptr,以判断是否找到匹配。下表给出了不同条件下返回并填入 low_bound_pos_ptr 和 high_bound_pos_ptr 的值。
| 返回值 | low_bound_pos_ptr | high_bound_pos_ptr | ||
|---|---|---|---|---|
| 找到匹配,且…… | ……列表已排序 | 索引最小的匹配元素的地址 | 索引最小的匹配元素的位置 | 索引最大的匹配元素的位置 |
| ……列表未排序 | 与 low_bound_pos_ptr 相同 |
|||
| 未找到匹配,且…… | ……列表已排序 | OPC_NIL |
次低于 high_bound_pos_ptr 的元素位置,若不存在则为 –1 |
插入 elem_ptr 以保持列表有序的位置 |
| ……列表未排序 | –1 | –1 |
注意: 该内核过程不是 MT 安全的,如 “Multi-Threading Safety“ 第 11 页所述。对共享列表的访问必须由外部串行化。
用途
当元素在列表中的位置未知时,用于在列表中搜索并返回特定元素。
错误
- 程序中止:段错误。(由于无效的列表指针或畸形列表)
参考
- 使用内核过程 op_prg_list_insert() 向列表插入元素
- 使用内核过程 op_prg_list_insert_sorted() 向有序列表插入元素