op_prg_list_insert_sorted()

Abstract

Inserts the element into the specified sorted list at the proper position, as defined by compare_proc.

Syntax

op_prg_list_insert_sorted (list_ptr, elem_ptr, compare_proc)
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 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 prg_list_init(). The list must be a sorted list.]
elem_ptr void* 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.]
compare_proc List_Compare_Proc function that determines the proper position for the element in the list.

Return Type

int

Index of the inserted element, or -1 if the insert fails.

Example

/* insert a sorted entry */
op_prg_list_insert_sorted (my_list, -1, prg_test_int_compare);
op_prg_list_insert_sorted (my_list, (num_elems / 2) * (num_elems / 2) + 1, prg_test_int_compare);

....

int
prg_test_int_compare (const void *value1, const void *value2)
   {
   FIN

   int i, j;
   i = (int) value1;
   j = (int) value2;

   if (i < j)
       FRET (1);
   else if (i > j)
       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 op_prg_list_insert_sorted() or prg_list_insert():

  • If you use op_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 any future calls to op_prg_list_insert_sorted() with this list to generate an error. At this point, you can call prg_list_sort() to make the list regain its sorted state.

The comparison procedure must accept two arguments (A and B) which are both pointers to the type of data structure or simple data type elements stored in the list-of-interest. The comparison procedure returns an integer code which indicates the precedence relationship between the two elements. The integer code takes on the following values:

1 indicates that A should be closer to the list head than B
-1 indicates that B should be closer to the list head than A
0 indicates that A and B are equal in rank

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

Note: If the element to be inserted is equal to an element already in the list, the newly inserted element will be placed after the element that is already in the list.

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 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