prg_list_access()
摘要
获取在指定列表的指定位置所存储元素的指针。
语法
prg_list_access (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
示例:
/* Obtain the i_th line. */
line = (char*) prg_list_access (line_list_ptr, i);
/* Decompose it into fields (field boundaries are */
/* indicated by spaces, tabs, slashes, or commas). */
field_list_ptr = prg_str_decomp (line, " ,/\t");
/* ...Incomplete lines are skipped. */
if (prg_list_size (field_list_ptr) < 6) continue;
/* Create a routing instruction structure. */
iri_ptr = (ip_rte_instruction*) prg_mem_alloc (sizeof (ip_rte_instruction));
/* ...First obtain the destination network and node fields. */
iri_ptr->dest_net = ip_rte_sup_str_to_addr (
(char*)(prg_list_access (field_list_ptr, IP_TBL_DEST_NET_FIELD));
iri_ptr->dest_node = ip_rte_sup_str_to_addr (
(char*) prg_list_access (field_list_ptr, IP_TBL_DEST_NODE_FIELD));
详情
通过此函数访问列表元素不会影响该元素的内容、作为列表成员的状态或在列表中的位置。不过,使用此函数返回的指针值的语句可以按需操纵该元素的内容。
此函数返回的指针值应当转换为合适的数据类型以访问元素的内容。下面给出一个示例,其中数据结构类型 block 的实例存储在列表中:
struct block *bptr;
bptr = (struct block *) prg_list_access (list_ptr, PRGC_LISTPOS_TAIL);
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享列表的访问必须由外部串行化。
用途:
提供了一种获取列表内包含的元素的指针的机制。通常用它来扫描、解析、搜索或以其他方式处理列表的内容。扫描可以先通过 prg_list_size() 确定列表中的元素数目来实现。可以借助此函数构造一个依次获取列表中每个元素指针的循环。
错误:
- 程序中止:段违例。(由于无效的列表指针或畸形列表)
- 可恢复错误:列表位置 (<pos_index>) 对该列表无效。
参考:
- 使用
prg_list_size()确定列表内元素的数量 - 使用
prg_list_remove()访问并从列表中移除元素 - 使用
prg_list_insert()向列表插入新元素 - 使用
prg_list_cell_from_index_get()获取指定索引处列表单元的引用