The function gets an vector that consists of groups of elements. All groups are of equal size, namely elements_in_group, so the total length of data vector should be whole multiple of elements_in_group. One element of each group is a key of sorting; it is identified by its zero-based position within the group, key_idx_in_group. The sorting procedure edits data and reorders groups in such a way that their keys become ordered ascending or descending, depending on sort_ascending flag.
The simplest case is plain sorting of a uniform array. In this case every element is an individual group, elements_in_group is 1 and key_idx_in_group is 0.
Other popular case is sorting of result of dict_to_vector(). In this case, every item of the original dictionary is represended in the vector by a pair of elements (elements_in_group is 2), so to sort items by their keys, the key_idx_in_group is 0 and to sort them by associated values, the key_idx_in_group is 1.
Similarly, elements_in_block is 2 for arrays like "lines" or "params" of a VSP page.
The function returns number of groups in the data vector
.