Elementary functions: improved help pages.
[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 version="5.0-subset Scilab" xml:id="intersect" 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>intersect</refname>
26
27     <refpurpose>returns the vector of common values of two
28     vectors</refpurpose>
29   </refnamediv>
30
31   <refsynopsisdiv>
32     <title>Calling Sequence</title>
33
34     <synopsis>
35       [v [,ka,kb]]=intersect(a,b)
36       [v [,ka,kb]]=intersect(a,b,orient)
37     </synopsis>
38   </refsynopsisdiv>
39
40   <refsection>
41     <title>Arguments</title>
42
43     <variablelist>
44       <varlistentry>
45         <term>a</term>
46
47         <listitem>
48           <para>vector of numbers or strings</para>
49         </listitem>
50       </varlistentry>
51
52       <varlistentry>
53         <term>b</term>
54
55         <listitem>
56           <para>vector of numbers or strings</para>
57         </listitem>
58       </varlistentry>
59
60       <varlistentry>
61         <term>orient</term>
62
63         <listitem>
64           <para>flag with possible values : 1 or "r", 2 or "c"</para>
65         </listitem>
66       </varlistentry>
67
68       <varlistentry>
69         <term>v</term>
70
71         <listitem>
72           <para>row vector of numbers or strings</para>
73         </listitem>
74       </varlistentry>
75
76       <varlistentry>
77         <term>ka</term>
78
79         <listitem>
80           <para>row vector of integers</para>
81         </listitem>
82       </varlistentry>
83
84       <varlistentry>
85         <term>kb</term>
86
87         <listitem>
88           <para>row vector of integers</para>
89         </listitem>
90       </varlistentry>
91     </variablelist>
92   </refsection>
93
94   <refsection>
95     <title>Description</title>
96
97     <para><literal>intersect(a,b)</literal> returns a sorted row vector of
98     common values of two vectors of <literal>a</literal> and
99     <literal>b</literal>.</para>
100
101     <para><literal>[v,ka,kb]=intersect(a,b)</literal> also returns index
102     vectors <literal>ka</literal> and <literal>kb</literal> such that
103     <literal>v=a(ka)</literal> and <literal>v=b(kb)</literal>.</para>
104
105     <para><literal>intersect(a,b,"r")</literal> or
106     <literal>intersect(a,b,1)</literal>returns the matrix formed by the
107     intersection of the unique rows of <literal>a</literal> and
108     <literal>b</literal> sorted in lexicographic ascending order. In this case
109     matrices <literal>a</literal> and <literal>b</literal> must have the same
110     number of columns.</para>
111
112     <para><literal>[v,ka,kb]=intersect(a,b,"r")</literal> also returns index
113     vectors <literal>ka</literal> and <literal>kb</literal> such that
114     <literal>v=a(ka,:)</literal> and <literal>v=b(kb,:)</literal>.</para>
115
116     <para><literal>intersect(a,b,"c")</literal> or
117     <literal>intersect(a,b,2)</literal>returns the matrix formed by the
118     intersection of the unique columns of <literal>a</literal> and
119     <literal>b</literal> sorted in lexicographic ascending order. In this case
120     matrices <literal>a</literal> and <literal>b</literal> must have the same
121     number of rows.</para>
122
123     <para><literal>[v,ka,kb]=intersect(a,b,"c")</literal> also returns index
124     vectors <literal>ka</literal> and <literal>kb</literal> such that
125     <literal>v=a(:,ka)</literal> and <literal>v=b(:,kb)</literal>.</para>
126   </refsection>
127
128   <refsection>
129     <title>Remark</title>
130
131     <para>NaN are considered as different from themselves so they are excluded
132     out of intersection in case of vector intersection.</para>
133   </refsection>
134
135   <refsection>
136     <title>Examples</title>
137
138     <programlisting role="example"><![CDATA[ 
139 A=round(5*rand(10,1));
140 B=round(5*rand(7,1));
141
142 intersect(A,B)
143 [N,ka,kb]=intersect(A,B)
144
145 intersect('a'+string(A),'a'+string(B))
146
147 intersect(int16(A),int16(B))
148
149 //with matrices
150  A = [0,0,1,1 1;
151       0,1,1,1,1;
152       2,0,1,1,1;
153       0,2,2,2,2;
154       2,0,1,1,1;
155       0,0,1,1,%nan];
156 B = [1,0,1;
157      1,0,2;
158      1,2,3;
159      2,0,4;
160      1,2,5;
161      %nan,0,6];
162
163 [v,ka,kb] = intersect(A,B,'c')
164 A(:,ka)
165  ]]></programlisting>
166   </refsection>
167
168   <refsection role="see also">
169 <title>See Also</title>
170
171     <simplelist type="inline">
172       <member><link linkend="unique">unique</link></member>
173
174       <member><link linkend="gsort">gsort</link></member>
175
176       <member><link linkend="union">union</link></member>
177     </simplelist>
178   </refsection>
179 </refentry>