1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
project.
Copyright (C) 1998-2018 OpenLink Software
This project is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; only version 2 of the License, dated June 1991.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
: template.sh,v 1.6 2009/04/14 11:39:26 source Exp $
-->
<refentry id="fn_rowvector_digit_sort">
<refmeta>
<refentrytitle>rowvector_digit_sort</refentrytitle>
<refmiscinfo>array</refmiscinfo>
</refmeta>
<refnamediv>
<refname>rowvector_digit_sort</refname>
<refpurpose>Performs a stable "digit" sort of a given array of arrays.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_rowvector_digit_sort">
<funcprototype id="fproto_rowvector_digit_sort">
<funcdef><function>rowvector_digit_sort</function></funcdef>
<paramdef>inout <parameter>data</parameter> vector</paramdef>
<paramdef>in <parameter>key_idx_in_row</parameter> integer</paramdef>
<paramdef>in <parameter>sort_ascending</parameter> integer</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_rowvector_digit_sort">
<title>Description</title>
<para>The function gets an vector that contains uniform arrays ("rows") as items, such as a result set produced by <link linkend="fn_exec"><function>exec</function></link>().
One element of each row is a key of sorting; it is identified by its zero-based position within the row, <parameter>key_idx_in_row</parameter>
(if the <parameter>data</parameter> vector is a result set then N-th elements of all rows are from N-th column of the result set).
The sorting procedure edits <parameter>data</parameter> and reorders rows in such a way that their keys become ordered ascending or descending,
depending on <parameter>sort_ascending</parameter> flag.</para>
<para>The performed sorting is stable. It means that it will not permutate rows in vain: it will preserve the relative order of any two rows that have equal keys.
Using this property, one may sort a result set by a "secondary sorting columns", starting with less significant and then by "primary sorting column".
E.g., if each row contain elements for country code and province code then it is possible to make two-column 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).</para>
<para>This function supports only integer values of sorting keys. <!-- To sort by strings, floating-point numbers etc., use
<link linkend="fn_rowvector_sort"><function>rowvector_sort</function></link>().
However, out of these two similar functions, only rowvector_digit_sort() is stable-sort. --></para>
</refsect1>
<refsect1 id="params_rowvector_digit_sort">
<title>Parameters</title>
<refsect2><title>data</title>
<para>A vector of rows to sort.</para>
</refsect2>
<refsect2><title>key_idx_in_row</title>
<para>Zero-based position of key element in row, should be nonnegative and less than the length of each row.</para>
</refsect2>
<refsect2><title>sort_ascending</title>
<para>Direction of sorting, nonzero for ascending sort, zero for descending.</para>
</refsect2>
</refsect1>
<refsect1 id="ret_rowvector_digit_sort"><title>Return Types</title>
<para>The function returns the length of the <parameter>data</parameter> vector.</para>
</refsect1>
<!--
<refsect1 id="errors_rowvector_digit_sort">
<title>Errors</title>
<para>This function can generate the following errors:</para>
<errorcode></errorcode>
</refsect1>
<refsect1 id="examples_rowvector_digit_sort">
<title>Examples</title>
<example id="ex_rowvector_digit_sort"><title></title>
<para></para>
<screen><![CDATA[
]]>
</screen>
</example>
</refsect1> -->
<refsect1 id="seealso_rowvector_digit_sort">
<title>See Also</title>
<para><link linkend="fn_gvector_digit_sort"><function>gvector_digit_sort()</function></link></para>
<para><link linkend="fn_gvector_sort"><function>gvector_sort()</function></link></para>
<!-- <para><link linkend="fn_rowvector_sort"><function>rowvector_sort</function></link></para> -->
</refsect1>
</refentry>
|
