op_prg_list_remove()
Abstract
Removes an element from the specified list, at the specified list position, and returns a pointer to the element.
Note: This KP is a macro call included for backward compatibility only. Use prg_list_remove() in new code.
Syntax
op_prg_list_remove (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 obtained from op_prg_list_create(); a list representing the contents of a file can be obtained from op_prg_gdf_read(); 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; acceptable values are OPC_LISTPOS_HEAD and OPC_LISTPOS_TAIL.] |
Return Type
void*
Pointer to the element removed from 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_frag_sup.ex.c); function (ip_frag_sup_insert()).
/* 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. */
op_prg_list_remove (dl_ptr->dgram_list_ptr, i);
/* Deallocate its memory */
op_prg_mem_free (ifl_ptr);
FRET (ip_pkptr)
}
Details
Elements can be removed from a list in any order, using the pos_index argument to position the removal. As elements are removed from a list at positions other than the list tail, elements between the removal point and the tail will have their position indices reduced by one. Attempting to remove an element at a negative position index, or at a position index larger than the list size will result in no element being removed, and a nil pointer will be returned (OPC_NIL).
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_remove (list_ptr, OPC_LISTPOS_HEAD);
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 remove an element from a list, and access the element. Typically this is used to sequentially process the contents of a list. List processing can be implemented by first determining the number of elements in a list via the KP op_prg_list_size(). Then a loop can be constructed that removes each element from the head of the list by calling op_prg_list_remove().
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_insert() to insert a new element into a list
- Use the KP op_prg_list_access() to obtain a pointer to an element in a list without removing it
- Use the KP op_prg_list_size() to determine the number of elements within a list