op_prg_list_elem_find()

Abstract

Finds an element in a list and returns a pointer to it.

Note: This KP is a macro call included for backward compatibility only. Use prg_list_elem_find() in new code.

Syntax

op_prg_list_elem_find (list_ptr, test_func, elem_ptr, low_bound_pos_ptr, high_bound_pos_ptr)
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().].
test_func List_Compare_Proc procedure called to determine if an element matches the search criteria (see Details for prototype)
elem_ptr void* element against which other elements in the list are compared
low_bound_pos_ptr int* Area to be filled with a pointer to a list element. See Table 13-1 in Details.
high_bound_pos_ptr int* Area to be filled with a pointer to a list element. See Table 13-1 in Details.

Return Type

void*

Pointer to the first matching element found in the specified list, or OPC_NIL.

Example

/* Check to see if the list already contains an element */
/* for this application.                                */
found_info = op_prg_list_elem_find (redirect_lptr, redirect_list_compare_proc,
	redirect_info, &low_index, &high_index);

....

int
redirect_list_compare_proc (const StbT_Redirect_Info* element1,
	const StbT_Redirect_Info* element2)
{
	if (element1->application == element2->application)
		{
		FRET (0);
		}
	else if (element1->application < element2->application)
		{
		FRET (1);
		}
	else
		{
		FRET (-1);
		}
}

Details

The source list specified by list_ptr must already be sorted (using test_func) before this function is called. There are two ways to sort the list in this manner:

The test function is prototyped as follows:

int
List_Compare_Proc (void* element1, void* element2)

This callback should accept two arguments that are both pointers to the type of data structure or simple data type elements stored in the list-of-interest. The callback should return one of the following values to indicate the precedence relationship between the two elements:

  • 1 if elem1 should be closer to the list head than elem2
  • 0 if elem1 and elem2 are equal in rank
  • -1 if elem2 should be closer to the list head than elem1

The test_func procedure is applied to a list element and elem_ptr to determine if a match is found. The following table shows the values returned and filled into low_bound_pos_ptr and high_bound_pos_ptr for different conditions.

Return Value low_bound_pos_ptr high_bound_pos_ptr
Match is found and… …list is sorted address of matching element with lowest index position of matching element with lowest index position of matching element with highest index
…list is unsorted same as low_bound_pos_ptr
No match is found and… …list is sorted OPC_NIL position of element next-lowest to high_bound_pos_ptr,
or –1 if none
position at which to insert elem_ptr to maintain a sorted list
…list is unsorted –1 –1

Note: This KP is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.

Purpose

To search for and return a particular element in a list, if the element’s position in the list is not known.

Errors

  • Program Abort: Segmentation violation. (due to an invalid list pointer or malformed list)

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