gvector_digit_sort — Performs a stable "digit" sort of a given array.
|inout data vector ,
|in elements_in_group integer ,
|in key_idx_in_group integer ,
|in sort_ascending integer
The function gets an vector that consists of groups of elements.
All groups are of equal size, namely
elements_in_group , so the total
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
reorders groups in such a way that their keys become ordered
ascending or descending, depending on
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.
The performed sorting is stable. It means that it will not permutate groups in vain: it will preserve the relative order of any two groups that have equal keys. Using this property, one may sort groups by a "secondary" key and then by "primary" key. E.g., if each group contain elements for country code and province code then it is possible to make two-field sorting by sorting first by province and then by country; that will work even if province codes are not globally unique (say, if they're enumerated from 1 in each country).
This function supports only integer values of sorting keys. To
sort by strings, floating-point numbers etc., use
gvector_sort (). However, out of these two
similar functions, only gvector_digit_sort() is stable-sort.
A group vector (gvector) to sort.
The number of vector elements in every group, usually 1, should be in range 1 to 1024.
Zero-based position of key element in group, should be
nonnegative and less than
Direction of sorting, nonzero for ascending sort, zero for descending.
The function returns number of groups in the
data vector .