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.
Header
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 causesprg_list_insert_sorted()to generate an error. At this point, you can callprg_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:
- 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.