* Bug 15734 fixed: intersect() dit not support complex numbers
[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  * Copyright (C) 2018 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20         xmlns:scilab="http://www.scilab.org" xml:id="intersect" xml:lang="en">
21     <refnamediv>
22         <refname>intersect</refname>
23         <refpurpose>
24             returns the unduplicated elements or rows or columns met in both input arrays
25         </refpurpose>
26     </refnamediv>
27     <refsynopsisdiv>
28         <title>Syntax</title>
29         <synopsis>
30             M = intersect(a, b)
31             M = intersect(a, b, orient)
32             [M, ka] = intersect(..)
33             [M, ka, kb] = intersect(..)
34         </synopsis>
35     </refsynopsisdiv>
36     <refsection>
37         <title>Arguments</title>
38         <variablelist>
39             <varlistentry>
40                 <term>a, b</term>
41                 <listitem>
42                     vectors, matrices or hypermatrices of encoded integers, real or complex
43                     numbers, or text. <varname>a</varname> and <varname>b</varname> must have
44                     the same datatype, but have independent sizes.
45                     For text inputs, UTF characters are accepted.
46                     <para/>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>orient</term>
51                 <listitem>
52                     flag with possible values : 1 or "r", 2 or "c". Can't be used if
53                     <varname>a</varname> or/and <varname>b</varname> is an hypermatrix.
54                     <para/>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>M</term>
59                 <listitem>
60                     <para>
61                         matrix of the same datatype as <varname>a</varname> and <varname>b</varname>.
62                         <itemizedlist>
63                             <listitem>
64                                 Without <varname>orient</varname>: <varname>M</varname> is a row vector.
65                             </listitem>
66                             <listitem>
67                                 With <literal>orient="r"|1</literal>: <varname>M</varname> is a
68                                 matrix stacking the common rows of <varname>a</varname> and
69                                 <varname>b</varname>.
70                             </listitem>
71                             <listitem>
72                                 With <literal>orient="c"|2</literal>: <varname>M</varname> is a
73                                 matrix stacking the common columns of <varname>a</varname> and
74                                 <varname>b</varname>.
75                             </listitem>
76                         </itemizedlist>
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>ka</term>
82                 <listitem>
83                     row vector of indices in <varname>a</varname>.
84                     <para/>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>kb</term>
89                 <listitem>
90                     row vector of indices in <varname>b</varname>.
91                     <para/>
92                 </listitem>
93             </varlistentry>
94         </variablelist>
95     </refsection>
96     <refsection>
97         <title>Description</title>
98         <para>
99             <literal>intersect(a,b)</literal> returns a row vector of unduplicated values
100             present in both <literal>a</literal> and <literal>b</literal> arrays. Values are
101             sorted in increasing order
102             <itemizedlist>
103                 <listitem>
104                     for complex numbers : par increasing magnitudes, then by increasing phases
105                 </listitem>
106                 <listitem>
107                     for text : in alphabetical order.
108                 </listitem>
109             </itemizedlist>
110         </para>
111         <warning>
112             Two NaN elements are always considered as different. So NaN or rows or columns having
113             NaN will never be in the result <literal>M</literal>.
114         </warning>
115         <para>
116             <literal>[M, ka, kb] = intersect(a,b)</literal> additionnaly returns the vectors
117             <literal>ka</literal> and <literal>kb</literal> of indices in <literal>a</literal>
118             and <literal>b</literal> of selected components firstly met, such that
119             <literal>M=a(ka)</literal> and <literal>M=b(kb)</literal>.
120         </para>
121         <refsect3>
122             <title>Common rows or columns</title>
123         <para>
124             When the <varname>orient</varname> argument is provided, the comparison is performed
125             between the rows of <literal>a</literal> and <literal>b</literal> -- each one being
126             considered as a whole --, or between their columns.
127         </para>
128         <para>
129             <literal>intersect(a,b,"r")</literal> or <literal>intersect(a,b,1)</literal> will return
130             the matrix of stacked unduplicated rows met in both  <literal>a</literal> and
131             <literal>b</literal>, sorted in lexicographic ascending order.
132             If <literal>a</literal> and <literal>b</literal> don't have the same number of columns,
133             [] is returned without comparing the values.
134         </para>
135         <para>
136             <literal>[M,ka,kb] = intersect(a,b,"r")</literal> additionnaly returns the vectors
137             <literal>ka</literal> and <literal>kb</literal> of the minimal indices of common rows,
138             respectively in <literal>a</literal> and <literal>b</literal>,
139             such that <literal>M=a(ka,:)</literal> and <literal>M=b(kb,:)</literal>.
140         </para>
141         <para>
142             <literal>intersect(a,b,"c")</literal> or <literal>intersect(a,b,2)</literal> does
143             the same for columns.
144         </para>
145         </refsect3>
146     </refsection>
147     <refsection>
148         <title>Examples</title>
149         <programlisting role="example"><![CDATA[
150 A = grand(3, 3, "uin", 0, 9)
151 B = grand(2, 4, "uin", 0, 9)
152 intersect(A, B)
153 [N, ka, kb] = intersect(A,B);
154 ka, kb
155  ]]></programlisting>
156     <screen><![CDATA[
157 --> A = grand(3, 3, "uin", 0, 9)
158  A  =
159    0.   6.   4.
160    6.   6.   6.
161    2.   7.   9.
162
163 --> B = grand(2, 4, "uin", 0, 9)
164  B  =
165    1.   8.   0.   2.
166    6.   2.   2.   1.
167
168 --> intersect(A, B)
169  ans  =
170    0.   2.   6.
171
172 --> [N, ka, kb] = intersect(A,B);
173 --> ka, kb
174  ka  =
175    1.   3.   2.
176  kb  =
177    5.   4.   2.
178 ]]></screen>
179     <para>
180         In the above example, note that 6 is met four times in A, at indices [2 4 5 8].
181         Only the minimal index 2 is returned in ka. Same situation for 2 in B.
182     </para>
183     <para/>
184     <para>
185     NaN values can never be in the result:
186     </para>
187     <programlisting role="example"><![CDATA[
188 %nan == %nan
189 intersect([1 -2 %nan 3 6], [%nan 1:3])
190  ]]></programlisting>
191     <screen><![CDATA[
192 --> %nan == %nan
193  ans  =
194   F
195
196 --> intersect([1 -2 %nan 3 6], [%nan 1:3])
197  ans  =
198    1.   3.
199 ]]></screen>
200     <para/>
201     <para>
202         intersect() can also process some characters or some texts. Since Scilab is great with UTF
203         characters, here is an example with some Arabic contents, getting characters present in
204         both sentences:
205     </para>
206         <programlisting role="example"><![CDATA[
207 A = strsplit("هو برنامج علمي كبير ""Scilab""")'
208 B = strsplit("فهو حر ومفتوح")'
209 intersect(A,B)
210  ]]></programlisting>
211     <screen><![CDATA[
212 --> A = strsplit("هو برنامج علمي كبير ""Scilab""")'
213  A  =
214 !ه  و     ب  ر  ن  ا  م  ج     ع  ل  م  ي     ك  ب  ي  ر     "  S  c  i  l  a  b  "  !
215
216 --> B = strsplit("فهو حر ومفتوح")'
217  B  =
218 !ف  ه  و     ح  ر     و  م  ف  ت  و  ح  !
219
220 --> intersect(A,B)
221  ans  =
222 !   ر  م  ه  و  !
223 ]]></screen>
224     <para/>
225     <para>
226         Column-wise or Row-wise processing of two matrices: Here we process 2 matrices of
227         signed 1-byte integers, and get the common columns:
228     </para>
229     <programlisting role="example"><![CDATA[
230 A = int8(grand(3,5,"uin",0,1))
231 B = int8(grand(3,9,"uin",0,1))
232 [M,ka,kb] = intersect(A, B, "c");
233 M, ka, kb
234  ]]></programlisting>
235     <screen><![CDATA[
236 --> A = int8(grand(3,5,"uin",0,1))
237  A  =
238   0  0  1  1  1
239   0  0  1  1  0
240   0  0  0  0  1
241
242 --> B = int8(grand(3,9,"uin",0,1))
243  B  =
244   1  0  1  1  1  0  1  1  1
245   1  0  0  1  1  1  0  0  0
246   1  0  1  0  1  1  1  0  0
247
248 --> [M,ka,kb] = intersect(A, B, "c");
249 --> M, ka, kb
250  M  =
251   0  1  1
252   0  0  1
253   0  1  0
254
255  ka  =
256    1.   5.   3.
257
258  kb  =
259    2.   3.   4.
260 ]]></screen>
261     </refsection>
262     <refsection role="see also">
263         <title>See also</title>
264         <simplelist type="inline">
265             <member>
266                 <link linkend="members">members</link>
267             </member>
268             <member>
269                 <link linkend="unique">unique</link>
270             </member>
271             <member>
272                 <link linkend="gsort">gsort</link>
273             </member>
274             <member>
275                 <link linkend="union">union</link>
276             </member>
277         </simplelist>
278     </refsection>
279     <refsection role="history">
280         <title>History</title>
281         <revhistory>
282             <revision>
283                 <revnumber>6.1.0</revnumber>
284                 <revdescription>
285                     complex numbers are now accepted.
286                 </revdescription>
287             </revision>
288         </revhistory>
289     </refsection>
290 </refentry>