prg_list_sort()

Abstract

Sorts a list according to a comparison algorithm implemented via a procedure argument.

Syntax

prg_list_sort (list_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().
compare_proc PrgT_List_Compare_Proc pointer to a C procedure used to perform element comparison.
Comparison procedures can be defined in process model function blocks, or external C files. If prg_list_sort() is being invoked from a process model executive or transition statement, a pointer to a comparison procedure can be obtained by referencing the procedure’s name, provided that a declaration of the procedure appears in the header block or temporary variable block of the process model. If prg_list_sort() is being invoked from an external C file, a pointer to a comparison procedure can be obtained the same way, provided that a declaration of the procedure appears in the file before the invocation.

Return Type

void

No return value.

prg_list_funcs.h

Example:

<the list to be sorted contains data structure elements (struct pair); the pair structure contains two>
<integer fields (x & y); sort the list so that the sum of the fields is largest near the list head>

/* comparison procedure definition */
sum_compare (struct pair *aptr, struct pair *bptr)
    {
    int asum, bsum;

    asum = aptr->x + aptr->y;
    bsum = bptr->x + bptr->y;

    if (asum > bsum)        return  1;
    else if (asum < bsum)   return -1;
    else	                   return  0;
    }

/* sort function invocation */
prg_list_sort (list_ptr, sum_compare);

Details

This function sorts a list by sub-dividing it and recursively sorting the list segments (a binary sort). This approach can be very slow for some lists. If faster sorting is needed, you can transfer a list to a vector (PrgT_Vector) and use prg_vector_sort().

The sorting order of elements is determined using a comparison procedure that is user-defined. This interface provides flexibility in the sorting metric, because arbitrary computations can be performed in the comparison procedure.

The prototype for compare_proc is given in PrgT_List_Compare_Proc.

As described in prg_list_insert_sorted(), an unsorted list becomes sorted after prg_list_sort() is applied to it.

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

Purpose:

Provides a mechanism to sort a list according to a user-defined metric. This is useful for organizing lists whose elements should be processed in an order that depends on their contents. For example the elements may represent requests that each have a priority value; sorting the list is therefore an operation that should be performed before processing begins, so that the higher priority requests can be accessed first.

Errors:

  • Program Abort: Segmentation violation. (due to invalid list pointer or malformed list).
  • Program Abort: Segmentation violation/Bus error. (due to an invalid compare_proc argument or coding error within the comparator procedure)

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