op_prg_list_insert_sorted()
摘要
将元素插入指定已排序列表中的合适位置,位置由 compare_proc 决定。
语法
op_prg_list_insert_sorted (list_ptr, elem_ptr, compare_proc)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
List* |
指向目标列表的指针。[列表指针可以从多个内核过程获得:空列表可由 prg_list_create() 获得;表示文件内容的列表可由 op_prg_gdf_read() 获得;列表可由用户代码分配并通过 prg_list_init() 初始化。该列表必须是已排序的列表。] |
elem_ptr |
void* |
指向待插入元素的指针。[任何数据类型都可以作为列表的元素,包括简单数据类型(如整数或字符串)和复杂数据结构。无需对元素指针进行类型转换。] |
compare_proc |
List_Compare_Proc |
决定元素在列表中合适位置的函数。 |
返回类型
int
所插入元素的索引;若插入失败则返回 -1。
示例
/* insert a sorted entry */
op_prg_list_insert_sorted (my_list, -1, prg_test_int_compare);
op_prg_list_insert_sorted (my_list, (num_elems / 2) * (num_elems / 2) + 1, prg_test_int_compare);
....
int
prg_test_int_compare (const void *value1, const void *value2)
{
FIN
int i, j;
i = (int) value1;
j = (int) value2;
if (i < j)
FRET (1);
else if (i > j)
FRET (-1);
else
FRET (0);
}
详情
若用于未排序的列表,会产生错误。
通过 prg_list_create() 创建的列表最初被认为是已排序的。你可以使用 op_prg_list_insert_sorted() 或 prg_list_insert() 向其添加元素:
- 如果使用
op_prg_list_insert_sorted(),列表将保持其有序特性。 - 如果使用 prg_list_insert(),即使元素被插入到正确的位置,列表也会被视为未排序。这将导致此后对该列表调用
op_prg_list_insert_sorted()时产生错误。此时可以调用 prg_list_sort() 使列表重新恢复有序状态。
比较过程必须接受两个参数(A 和 B),二者均为指向列表中所存储的数据结构类型或简单数据类型元素的指针。比较过程返回一个整数代码,指示两个元素之间的优先关系。该整数代码取以下值:
| 1 | 表示 A 应比 B 更靠近列表表头 |
| -1 | 表示 B 应比 A 更靠近列表表头 |
| 0 | 表示 A 与 B 优先级相同 |
compare_proc 作用于列表中的元素,将其与传递给本函数的 elem_ptr 参数进行比较。
注意: 如果要插入的元素与列表中已有元素相等,新插入的元素将被放置在已有元素之后。
注意: 该内核过程不是 MT 安全的,如 “Multi-Threading Safety“ 第 11 页所述。对共享列表的访问必须由外部串行化。
用途
向已排序列表中插入元素,并按 compare_proc 的定义保持列表元素的排序。
错误
- 可恢复错误:尝试对未排序列表执行有序插入。
参考
- 使用 prg_list_access() 访问列表元素。
- 使用 prg_list_create() 创建已排序列表。
- 使用 prg_list_remove() 从列表中移除元素。
- 使用 prg_list_sort() 将已被视为未排序的列表重新变为已排序列表。