prg_list_remove()
摘要
从指定列表的指定位置移除一个元素,并返回指向该元素的指针。
语法
prg_list_remove (list_ptr, pos_index)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
PrgT_List* |
指向目标列表的指针。 可以从多个函数获得列表指针:可从 prg_list_create() 获得一个空列表;从 prg_gdf_read() 获得表示文件内容的列表;或者由用户代码分配一个列表并通过 prg_list_init() 初始化。 |
pos_index |
int |
要访问的元素在列表中的数字位置索引。 位置索引从列表头部的 0 开始,逐次加 1 直到尾部。除显式的数字位置索引外,也可以指定抽象的列表位置索引;可取的值为 PRGC_LISTPOS_HEAD 和 PRGC_LISTPOS_TAIL。 |
返回类型
Vartype*
指向从指定列表中移除的元素的指针。[如果指定的位置索引大于指定列表尾部元素的索引,或者索引小于零,则返回符号常量 PRGC_NIL 所代表的特殊值。
头文件
prg_list_funcs.h
示例:
/* Test if this completes the overall datagram. */
if (ifl_ptr->total_bytes_rcvd == ifl_ptr->total_bytes_reqd)
{
/* --trace "if" statement removed from example-- */
/* Extract the overall ip datagram so that it can be returned. */
ip_pkptr = ifl_ptr->ip_pkptr;
/* remove the ip fragment record from the datagram list. */
prg_list_remove (dl_ptr->dgram_list_ptr, i);
/* Deallocate its memory */
prg_mem_free (ifl_ptr);
FRET (ip_pkptr)
}
详情
列表元素可以按任意顺序移除,使用 pos_index 参数定位移除位置。当从列表尾部以外的位置移除元素时,移除点与尾部之间的元素的位置索引将减 1。试图在负数位置索引处移除元素,或在大于列表大小的位置索引处移除元素,将导致没有元素被移除,并返回空指针(PRGC_NIL)。
此函数返回的指针值应当转换为合适的数据类型以访问元素的内容。下面给出一个示例,其中数据结构类型 block 的实例存储在列表中:
struct block *bptr;
bptr = (struct block *) prg_list_remove (list_ptr, PRGC_LISTPOS_HEAD);
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享列表的访问必须由外部串行化。
用途:
提供了一种从列表中移除元素并访问该元素的机制。通常用于顺序处理列表的内容。列表处理可以先通过函数 prg_list_size() 确定列表中的元素数目来实现,然后构造一个循环,通过调用 prg_list_remove() 依次从列表头部移除每个元素。
错误:
- 程序中止:段违例。(由于无效的列表指针或畸形列表)
- 可恢复错误:列表位置 (<pos_index>) 超出范围。
参考:
- 使用
prg_list_insert()向列表插入新元素 - 使用
prg_list_access()获取列表中元素的指针而不将其移除 - 使用
prg_list_size()确定列表内元素的数量