prg_list_insert_sorted()
摘要
在由用户指定的比较过程所确定的排序位置向列表中插入一个元素。
语法
prg_list_insert_sorted (list_ptr, element_ptr, compare_proc)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
PrgT_List* |
指向目标列表的指针。 获取列表指针的途径有多种:空列表可由 prg_list_create() 获得;表示文件内容的列表可由 prg_gdf_read() 获得;也可以由用户代码分配列表并通过 prg_list_init() 初始化。 |
element_ptr |
Vartype* |
指向待插入元素的指针。 任何数据类型都可以作为列表元素,包括简单数据类型(如整数或字符串)和复杂数据结构。无需对元素指针进行类型转换(注意 Vartype* 并非真实的数据类型,只是一种符号约定)。 |
compare_proc |
PrgT_List_Compare_Proc |
确定元素在列表中合适位置的函数。 |
返回类型
Prg_List_Cell *
包含已插入元素的列表单元。
头文件
prg_list_funcs.h
示例:
/* Insert the address structure into the specified protocol's */
/* address list; keep the list sorted by hname. */
prg_list_insert_sorted (OmsI_Basetraf_Node_Addr_List_Array [protocol],
node_addr_ptr, oms_topo_node_addr_comp);
....
int
oms_topo_node_addr_comp (const void* node_addr_ptr1, const void* node_addr_ptr2)
{
OmsT_Basetraf_Node_Addr *naptr1, *naptr2;
int compare_ind;
naptr1 = (OmsT_Basetraf_Node_Addr*) node_addr_ptr1;
naptr2 = (OmsT_Basetraf_Node_Addr*) node_addr_ptr2;
compare_ind = strcmp (naptr1->hname, naptr2->hname);
if (compare_ind < 0)
{ FRET (1); }
else if (compare_ind > 0)
{ FRET (-1); }
else
{ FRET (0); }
}
详情
若用于未排序的列表,会产生错误。
通过 prg_list_create() 创建的列表最初被认为是已排序的。既可以用 prg_list_insert_sorted(),也可以用 prg_list_insert() 向其添加元素。
- 如果使用
prg_list_insert_sorted(),列表将保持其排序状态。 - 如果使用
prg_list_insert(),即使元素被插入到正确的位置,列表也会被视为未排序。这会导致prg_list_insert_sorted()产生错误。此时可以调用prg_list_sorted()使列表重新恢复排序状态。
compare_proc 会被作用于列表中的元素,将它们与传递给本函数的 elem_ptr 参数进行比较。compare_proc 的原型见 PrgT_List_Compare_Proc。
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享列表的访问必须由外部串行化。
用途:
向已排序的列表中插入元素,并按照 compare_proc 定义的规则保持列表中元素的顺序。
错误:
- 可恢复错误:试图对未排序的列表执行排序插入。
参考:
- 使用
prg_list_access()访问列表中的元素。 - 使用
prg_list_create()创建已排序的列表。 - 使用
prg_list_remove()从列表中移除元素。 - 使用
prg_list_sort()将已被视为未排序的列表重新变为已排序的列表。