prg_list_insert()
Abstract
Inserts a data element into a list at a position specified by index.
Syntax
prg_list_insert (list_ptr, element_ptr, pos_index)
| Argument | Type | Description |
|---|---|---|
list_ptr |
PrgT_List* |
pointer to the list-of-interest. A pointer to a list can be obtained from several functions: an empty list can be obtained from prg_list_create(); a list representing the contents of a file can be obtained from prg_gdf_read(); a list can be allocated by user code and initialized via prg_list_init(). |
element_ptr |
Vartype* |
pointer to the element to be inserted. Any data types can be elements of a list, including simple data types (such as integers or character strings) and complex data structures. Casting of the element pointer is not necessary (note that Vartype* is not a real data type, but a notational convention). |
pos_index |
int |
numeric position index of the element to be inserted into the list. Position indices start at 0 at the head, incrementing by one until the tail is reached. You can specify either an explicit numeric position index or the symbolic constants ( PRGC_LISTPOS_HEAD or PRGC_LISTPOS_TAIL.) |
Return Type
Prg_List_Cell *
The list cell containing the inserted element.
Header
prg_list_funcs.h
Example:
/* 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);
}
Details
Elements can be inserted into a list in any order, using the pos_index argument to position the insertion. As elements are inserted in a list at positions other than the list tail, elements between the insertion point and the tail will have their position indices shifted up by one.
The special symbolic list positions PRGC_LISTPOS_HEAD and PRGC_LISTPOS_TAIL can be used to insert elements at the head or the tail of the list. It is recommended that these constants be used whenever possible.
This function does not guard against redundant insertions of elements into the list. In other words, the same element address is allowed to be present at multiple locations in the list.
WARNING: This function 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 insert elements into a list. Lists are typically constructed to hold textual information (such as routing or address translation tables), or to hold a set of packets stored temporarily in a processor.
Errors:
- Program Abort: Segmentation violation. (due to an illegal list pointer or malformed list)
Reference:
- use
prg_list_remove()to remove an element from a list - use
prg_list_create()to have the Programming support library allocate a new, empty list - use
prg_list_init()to prepare a new, empty list which has been allocated by user code - use
prg_list_free()to remove and deallocate all elements on a list (retaining the list itself)