prg_list_elem_find()
摘要
在源列表中查找元素,并返回指向它的指针。
语法
prg_list_elem_find (list_ptr, test_func, elem_ptr, low_bound_pos_ptr, high_bound_pos_ptr)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
PrgT_List * |
指向目标列表的指针 |
test_func |
PrgT_List_Compare_Proc |
用于判断元素是否匹配搜索条件的过程 |
elem_ptr |
void * |
列表中其他元素与之比较的元素。 |
low_bound_pos_ptr |
int * |
将被填入列表元素指针的区域。参见详情。 |
high_bound_pos_ptr |
int * |
将被填入列表元素指针的区域。参见详情。 |
返回类型
Vartype *
指向找到的元素的指针;若未找到任何元素,则返回 PRGC_NIL。
头文件
prg_list_funcs.h
示例:
/* use the 'find' to find in the sorted list */
j = (int) prg_list_elem_find (my_list, prg_test_int_compare,
(const void *) ((num_elems / 2) * (num_elems / 2)),
PRGC_NIL, PRGC_NIL);
if (j != ((num_elems / 2) * (num_elems / 2))) {
aprintf (FLINE, "did not find element (%d) as expected, found %d instead",
(num_elems / 2) * (num_elems / 2), j);
}
....
int
prg_test_int_compare (const void *value1, const void *value2)
{
int i, j;
i = (int) value1;
j = (int) value2;
if (i < j) { FRET (1); }
else if (i > j) { FRET (-1); }
else { FRET (0); }
}
详情
list_ptr 指定的源列表必须在调用此函数之前已经按 test_func 排好序。有两种方式可以以这种方式对列表排序:
- 使用相同的比较过程调用
prg_list_sort() - 使用
prg_list_insert_sorted()将所有项添加到列表
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 |
测试函数的原型见 PrgT_List_Compare_Proc。
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享列表的访问必须由外部串行化。
用途:
当元素在列表中的位置未知时,用于在 PrgT_List 中搜索并返回特定元素。
错误:
- 程序中止:段违例。(由于无效的列表指针或畸形列表)
参考:
- 使用
prg_list_insert()向列表插入元素 - 使用
prg_list_insert_sorted()向有序列表插入元素