e3d418bcb0aba6e8322eb246a5ea948d5b97e9c2
[scilab.git] / scilab / modules / elementary_functions / help / en_US / searchandsort / lex_sort.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="lex_sort" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate$</pubdate>
22   </info>
23
24   <refnamediv>
25     <refname>lex_sort</refname>
26
27     <refpurpose>lexicographic matrix rows sorting</refpurpose>
28   </refnamediv>
29
30   <refsynopsisdiv>
31     <title>Calling Sequence</title>
32
33     <synopsis>[N, [k]]=lex_sort(M [,sel] [,'unique'])
34 </synopsis>
35   </refsynopsisdiv>
36
37   <refsection>
38     <title>Arguments</title>
39
40     <variablelist>
41       <varlistentry>
42         <term>M</term>
43
44         <listitem>
45           <para>real matrix</para>
46         </listitem>
47       </varlistentry>
48
49       <varlistentry>
50         <term>N</term>
51
52         <listitem>
53           <para>real matrix</para>
54         </listitem>
55       </varlistentry>
56
57       <varlistentry>
58         <term>k</term>
59
60         <listitem>
61           <para>column vector of integers</para>
62         </listitem>
63       </varlistentry>
64     </variablelist>
65   </refsection>
66
67   <refsection>
68     <title>Description</title>
69
70     <para>the <literal>lex_sort</literal> function is now obsolete. It can be
71     replaced by functions <link linkend="gsort">gsort</link> and <link
72     linkend="unique">unique</link>.</para>
73
74     <para><literal>N=lex_sort(M)</literal> sorts the rows (as a group) of the
75     matrix <literal>M</literal> in ascending order. If required the output
76     argument <literal>k</literal> contains the ordering:
77     <literal>[N,k]=lex_sort(M)</literal> returns <literal>k</literal> such as
78     <literal>N</literal> is uequal to <literal>M(k,:)</literal> .</para>
79
80     <para><literal>N=lex_sort(M,sel [,'unique'])</literal> produces the same
81     result as the following sequence of instructions:</para>
82
83     <programlisting role = ""><![CDATA[ 
84 [N,k]=lex_sort(M(:,sel) [,'unique']);
85 N=M(k,:)
86  ]]></programlisting>
87
88     <para>The <literal>'unique'</literal> flag has to be given if one wants to
89     retain only unique rows in the result. Note that
90     <literal>lex_sort(M,sel,'unique')</literal> retains only rows such that
91     M(:,sel) are unique.</para>
92   </refsection>
93
94   <refsection>
95     <title>Examples</title>
96
97     <programlisting role="example"><![CDATA[ 
98 M=round(2*rand(20,3));
99
100 lex_sort(M)
101 lex_sort(M,'unique')
102 [N,k]=lex_sort(M,[1 3],'unique')
103  ]]></programlisting>
104   </refsection>
105
106   <refsection role="see also">
107 <title>See Also</title>
108
109     <simplelist type="inline">
110       <member><link linkend="gsort">gsort</link></member>
111
112       <member><link linkend="unique">unique</link></member>
113     </simplelist>
114   </refsection>
115 </refentry>