prg_list_insert_sorted()

Abstract

Inserts an element into a list at a sorted position determined by a user-specified comparison procedure.

Syntax

prg_list_insert_sorted (list_ptr, element_ptr, compare_proc)
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).
compare_proc PrgT_List_Compare_Proc function that determines the proper position for the element in the list.

Return Type

Prg_List_Cell *

The list cell containing the inserted element.

prg_list_funcs.h

Example:

/* Insert the address structure into the specified protocol's    */
/* address list; keep the list sorted by hname. */
prg_list_insert_sorted (OmsI_Basetraf_Node_Addr_List_Array [protocol], 
	node_addr_ptr, oms_topo_node_addr_comp);

....

int
oms_topo_node_addr_comp (const void* node_addr_ptr1, const void* node_addr_ptr2)
	{
	OmsT_Basetraf_Node_Addr *naptr1, *naptr2;
	int compare_ind;

	naptr1 = (OmsT_Basetraf_Node_Addr*) node_addr_ptr1;
	naptr2 = (OmsT_Basetraf_Node_Addr*) node_addr_ptr2;
	compare_ind = strcmp (naptr1->hname, naptr2->hname);
	if (compare_ind < 0)
		{ FRET (1); }
	else if (compare_ind > 0)
		{ FRET (-1); }
	else
		{ FRET (0); }
	}

Details

Generates an error if used with an unsorted list.

A list created with prg_list_create() is initially considered to be sorted. You can add elements to it using either prg_list_insert_sorted() or prg_list_insert().

  • If you use prg_list_insert_sorted(), the list preserves its sorted nature.
  • If you use prg_list_insert(), the list will be considered unsorted, even if the element has been inserted in the correct position. This causes prg_list_insert_sorted() to generate an error. At this point, you can call prg_list_sorted() to make the list regain its sorted state.

The compare_proc is called on elements in the list, comparing them to the elem_ptr argument passed to this function. The prototype for compare_proc is given in PrgT_List_Compare_Proc.

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

Purpose:

To insert an element into a sorted list, preserving the ordering of elements in the list, as defined by the compare_proc.

Errors:

  • Recoverable error: Sorted insertion attempted on unsorted 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