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 页。对共享列表的访问必须由外部串行化。

用途:

提供一种向列表中插入元素的机制。列表通常用于保存文本信息(如路由表或地址转换表),或保存临时存储在处理器中的一组数据包。

错误:

  • 程序中止:段违例。(由于非法列表指针或畸形列表)

参考:

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com