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
- Use prg_list_access() to access elements of the list.
- Use prg_list_create() to create a sorted list.
- Use prg_list_remove() to remove elements from the list.
- Use prg_list_sort() to change a list that has come to be considered unsorted a sorted list again.