Help check: validate the help files on compilation against a derivated docbook schema
[scilab.git] / scilab / modules / elementary_functions / help / en_US / setoperations / intersect.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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="intersect" xml:lang="en">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>intersect</refname>
19     <refpurpose>returns the vector of common values of two
20     vectors</refpurpose>
21   </refnamediv>
22   <refsynopsisdiv>
23     <title>Calling Sequence</title>
24     <synopsis>[v [,ka,kb]]=intersect(a,b)</synopsis>
25     <synopsis>[v [,ka,kb]]=intersect(a,b,orient)</synopsis>
26   </refsynopsisdiv>
27   <refsection>
28     <title>Arguments</title>
29     <variablelist>
30       <varlistentry>
31         <term>a</term>
32         <listitem>
33           <para>vector of numbers or strings</para>
34         </listitem>
35       </varlistentry>
36       <varlistentry>
37         <term>b</term>
38         <listitem>
39           <para>vector of numbers or strings</para>
40         </listitem>
41       </varlistentry>
42       <varlistentry>
43         <term>orient</term>
44         <listitem>
45           <para>flag with possible values : 1 or "r", 2 or "c"</para>
46         </listitem>
47       </varlistentry>
48       <varlistentry>
49         <term>v</term>
50         <listitem>
51           <para>row vector of numbers or strings</para>
52         </listitem>
53       </varlistentry>
54       <varlistentry>
55         <term>ka</term>
56         <listitem>
57           <para>row vector of integers</para>
58         </listitem>
59       </varlistentry>
60       <varlistentry>
61         <term>kb</term>
62         <listitem>
63           <para>row vector of integers</para>
64         </listitem>
65       </varlistentry>
66     </variablelist>
67   </refsection>
68   <refsection>
69     <title>Description</title>
70     <para><literal>intersect(a,b)</literal> returns a sorted row vector of
71     common values of two vectors of <literal>a</literal> and
72     <literal>b</literal>.</para>
73     <para><literal>[v,ka,kb]=intersect(a,b)</literal> also returns index
74     vectors <literal>ka</literal> and <literal>kb</literal> such that
75     <literal>v=a(ka)</literal> and <literal>v=b(kb)</literal>.</para>
76     <para><literal>intersect(a,b,"r")</literal> or
77     <literal>intersect(a,b,1)</literal>returns the matrix formed by the
78     intersection of the unique rows of <literal>a</literal> and
79     <literal>b</literal> sorted in lexicographic ascending order. In this case
80     matrices <literal>a</literal> and <literal>b</literal> must have the same
81     number of columns.</para>
82     <para><literal>[v,ka,kb]=intersect(a,b,"r")</literal> also returns index
83     vectors <literal>ka</literal> and <literal>kb</literal> such that
84     <literal>v=a(ka,:)</literal> and <literal>v=b(kb,:)</literal>.</para>
85     <para><literal>intersect(a,b,"c")</literal> or
86     <literal>intersect(a,b,2)</literal>returns the matrix formed by the
87     intersection of the unique columns of <literal>a</literal> and
88     <literal>b</literal> sorted in lexicographic ascending order. In this case
89     matrices <literal>a</literal> and <literal>b</literal> must have the same
90     number of rows.</para>
91     <para><literal>[v,ka,kb]=intersect(a,b,"c")</literal> also returns index
92     vectors <literal>ka</literal> and <literal>kb</literal> such that
93     <literal>v=a(:,ka)</literal> and <literal>v=b(:,kb)</literal>.</para>
94   </refsection>
95   <refsection>
96     <title>Remark</title>
97     <para>NaN are considered as different from themselves so they are excluded
98     out of intersection in case of vector intersection.</para>
99   </refsection>
100   <refsection>
101     <title>Examples</title>
102     <programlisting role="example"><![CDATA[ 
103 A=round(5*rand(10,1));
104 B=round(5*rand(7,1));
105
106 intersect(A,B)
107 [N,ka,kb]=intersect(A,B)
108
109 intersect('a'+string(A),'a'+string(B))
110
111 intersect(int16(A),int16(B))
112
113 //with matrices
114  A = [0,0,1,1 1;
115       0,1,1,1,1;
116       2,0,1,1,1;
117       0,2,2,2,2;
118       2,0,1,1,1;
119       0,0,1,1,%nan];
120 B = [1,0,1;
121      1,0,2;
122      1,2,3;
123      2,0,4;
124      1,2,5;
125      %nan,0,6];
126
127 [v,ka,kb] = intersect(A,B,'c')
128 A(:,ka)
129  ]]></programlisting>
130   </refsection>
131   <refsection role="see also">
132     <title>See Also</title>
133     <simplelist type="inline">
134       <member>
135         <link linkend="unique">unique</link>
136       </member>
137       <member>
138         <link linkend="gsort">gsort</link>
139       </member>
140       <member>
141         <link linkend="union">union</link>
142       </member>
143     </simplelist>
144   </refsection>
145 </refentry>