prg_list_insert()
摘要
在索引指定的位置向列表中插入一个数据元素。
语法
prg_list_insert (list_ptr, element_ptr, pos_index)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
PrgT_List* |
指向目标列表的指针。 获取列表指针的途径有多种:空列表可由 prg_list_create() 获得;表示文件内容的列表可由 prg_gdf_read() 获得;也可以由用户代码分配列表并通过 prg_list_init() 初始化。 |
element_ptr |
Vartype* |
指向待插入元素的指针。 任何数据类型都可以作为列表元素,包括简单数据类型(如整数或字符串)和复杂数据结构。无需对元素指针进行类型转换(注意 Vartype* 并非真实的数据类型,只是一种符号约定)。 |
pos_index |
int |
待插入元素在列表中的数字位置索引。 位置索引从列表头部的 0 开始逐次加一,直到列表尾部。可以指定明确的数字位置索引,也可以使用符号常量( PRGC_LISTPOS_HEAD 或 PRGC_LISTPOS_TAIL。) |
返回类型
Prg_List_Cell *
包含已插入元素的列表单元。
头文件
prg_list_funcs.h
示例:
/* allocate a list */
list_ptr = (PrgT_List *) prg_mem_alloc (sizeof (PrgT_List));
/* initialize a list */
prg_list_init (list_ptr);
/** move the contents of subqueue #0 into the list **/
/* determine the number of packets in the subqueue */
subq_size = op_subq_stat (0, OPC_QSTAT_PKSIZE);
for (i = 0; i < subq_size; i++)
{
/* take a single packet from the subqueue head */
pkptr = op_subq_pk_remove (0, OPC_QPOS_HEAD);
/* insert the packet onto the list tail */
prg_list_insert (list_ptr, pkptr, PRGC_LISTPOS_TAIL);
}
详情
元素可以按任意顺序插入列表,通过 pos_index 参数确定插入位置。当在列表尾部以外的位置插入元素时,插入点与列表尾部之间各元素的位置索引将依次上移一位。
可以使用特殊符号列表位置 PRGC_LISTPOS_HEAD 和 PRGC_LISTPOS_TAIL 在列表头部或尾部插入元素。建议尽可能使用这些常量。
该函数不会防止向列表中重复插入元素。换言之,同一元素地址允许出现在列表中的多个位置。
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享列表的访问必须由外部串行化。
用途:
提供一种向列表中插入元素的机制。列表通常用于保存文本信息(如路由表或地址转换表),或保存临时存储在处理器中的一组数据包。
错误:
- 程序中止:段违例。(由于非法列表指针或畸形列表)
参考:
- 使用
prg_list_remove()从列表中移除元素 - 使用
prg_list_create()让 Programming support library 分配一个新的空列表 - 使用
prg_list_init()准备一个由用户代码分配的新空列表 - 使用
prg_list_free()移除并释放列表上的所有元素(保留列表本身)