prg_list_remove()

Abstract

Removes an element from the specified list, at the specified list position, and returns a pointer to the element.

Syntax

prg_list_remove (list_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().
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 PRGC_LISTPOS_HEAD and PRGC_LISTPOS_TAIL.

Return Type

Vartype*

Pointer to the element removed from the specified list.[The special value represented by the symbolic constant PRGC_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.

prg_list_funcs.h

Example:

/* 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)
	}

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 (PRGC_NIL).

The pointer value returned by this function 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 *) prg_list_remove (list_ptr, PRGC_LISTPOS_HEAD);

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 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 function prg_list_size(). Then a loop can be constructed that removes each element from the head of the list by calling 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:

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com