op_prg_list_access()
Abstract
Obtains a pointer to an element stored in the specified list, at the specified list position.
Note: This KP is a macro call included for backward compatibility only. Use prg_list_access() in new code.
Syntax
op_prg_list_access (list_ptr, pos_index)
| Argument | Type | Description |
|---|---|---|
list_ptr |
List* |
pointer to the list-of-interest [A pointer to a list can be obtained from several KPs: an empty list can be originally obtained from op_prg_list_create(), a list representing the contents of a file can be obtained from op_prg_gdf_read(), or a list can be allocated by user code, and initialized via op_prg_list_init().]. |
pos_index |
int |
numeric position index of the element to be accessed in the list [Position indices start at 0 at the head of the list, and increment by one until the tail is reached. Instead of an explicit numeric position index, an abstract list position index may be specified; the acceptable values are OPC_LISTPOS_HEAD and OPC_LISTPOS_TAIL.] |
Return Type
void*
Pointer to the element accessed within the specified list.
The special value represented by the symbolic constant OPC_NIL will be returned if the specified position index is larger than the index of the tail element in the specified list, or if the index is less than zero.
Example
Excerpt from: example model (std/ip); external C file (ip_rte_sup.ex.c); function (ip_rte_sup_list_parse()).
/* Obtain the i_th line. */
line = (char*) op_prg_list_access (line_list_ptr, i);
/* Decompose it into fields (field boundaries are */
/* indicated by spaces, tabs, slashes, or commas). */
field_list_ptr = op_prg_str_decomp (line, " ,/\t");
/* ...Incomplete lines are skipped. */
if (op_prg_list_size (field_list_ptr) < 6) continue;
/* Create a routing instruction structure. */
iri_ptr = (ip_rte_instruction*) op_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*)(op_prg_list_access (field_list_ptr, IP_TBL_DEST_NET_FIELD));
iri_ptr->dest_node = ip_rte_sup_str_to_addr (
(char*) op_prg_list_access (field_list_ptr, IP_TBL_DEST_NODE_FIELD));
Details
Accessing a list element via this KP does not affect the element’s contents, status as a member of the list, or position within the list. However, statements that use the pointer value returned by this KP can manipulate the contents of the element, if desired.
The pointer value returned by this KP should be cast into the appropriate data type to access the element’s contents. An example is shown below, in which instances of the data structure type block are stored in a list:
struct block *bptr;
bptr = (struct block *) op_prg_list_access (list_ptr, OPC_LISTPOS_TAIL);
Note: This KP is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.
Purpose
Provides a mechanism to obtain the pointer of an element contained within a list. Typically this is used to scan the contents of a list, parse, search, or otherwise process its contents. Scanning can be implemented by first determining the number of elements in a list via the KP op_prg_list_size(). A loop can be constructed which obtains the pointer to each element in the list in turn, using this KP.
Errors
- Program Abort: Segmentation violation. (due to invalid list pointer or malformed list)
- Recoverable Error: List position (
<pos_index>) is out-of-range.
Reference
- Use the KP op_prg_list_size() to determine the number of elements within a list
- Use the KP op_prg_list_remove() to access and remove an element from a list
- Use the KP op_prg_list_insert() to insert a new element into a list