203820453622c6db23359b8e75796db17d5bf8ec
[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                     <para>
43                         vectors, matrices or hypermatrices of encoded integers, decimal real
44                         numbers, or text. <varname>a</varname> and <varname>b</varname> must have
45                         the same datatype, but have independent sizes.
46                         For text inputs, UTF characters are accepted.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>orient</term>
52                 <listitem>
53                     <para>
54                         flag with possible values : 1 or "r", 2 or "c". Can't be used if
55                         <varname>a</varname> or/and <varname>b</varname> is an hypermatrix.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>M</term>
61                 <listitem>
62                     <para>
63                         matrix of the same datatype as <varname>a</varname> and <varname>b</varname>.
64                         <itemizedlist>
65                             <listitem>
66                                 Without <varname>orient</varname>: <varname>M</varname> is a row vector.
67                             </listitem>
68                             <listitem>
69                                 With <literal>orient="r"|1</literal>: <varname>M</varname> is a
70                                 matrix stacking the common rows of <varname>a</varname> and
71                                 <varname>b</varname>.
72                             </listitem>
73                             <listitem>
74                                 With <literal>orient="c"|2</literal>: <varname>M</varname> is a
75                                 matrix stacking the common columns of <varname>a</varname> and
76                                 <varname>b</varname>.
77                             </listitem>
78                         </itemizedlist>
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>ka</term>
84                 <listitem>
85                     <para>
86                         row vector of indices in <varname>a</varname>.
87                     </para>
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>kb</term>
92                 <listitem>
93                     <para>
94                         row vector of indices in <varname>b</varname>.
95                     </para>
96                 </listitem>
97             </varlistentry>
98         </variablelist>
99     </refsection>
100     <refsection>
101         <title>Description</title>
102         <para>
103             <literal>intersect(a,b)</literal> returns a row vector of unduplicated sorted values
104             present in both <literal>a</literal> and <literal>b</literal> arrays.
105         </para>
106         <warning>
107             Two NaN elements are always considered as different. So NaN or rows or columns having
108             NaN will never be in the result <literal>M</literal>.
109         </warning>
110         <para>
111             <literal>[M, ka, kb] = intersect(a,b)</literal> additionnaly returns the vectors
112             <literal>ka</literal> and <literal>kb</literal> of indices in <literal>a</literal>
113             and <literal>b</literal> of selected components firstly met, such that
114             <literal>M=a(ka)</literal> and <literal>M=b(kb)</literal>.
115         </para>
116         <refsect3>
117             <title>Common rows or columns</title>
118         <para>
119             When the <varname>orient</varname> argument is provided, the comparison is performed
120             between the rows of <literal>a</literal> and <literal>b</literal> -- each one being
121             considered as a whole --, or between their columns.
122         </para>
123         <para>
124             <literal>intersect(a,b,"r")</literal> or <literal>intersect(a,b,1)</literal> will return
125             the matrix of stacked unduplicated rows met in both  <literal>a</literal> and
126             <literal>b</literal>, sorted in lexicographic ascending order.
127             If <literal>a</literal> and <literal>b</literal> don't have the same number of columns,
128             [] is returned without comparing the values.
129         </para>
130         <para>
131             <literal>[M,ka,kb] = intersect(a,b,"r")</literal> additionnaly returns the vectors
132             <literal>ka</literal> and <literal>kb</literal> of the minimal indices of common rows,
133             respectively in <literal>a</literal> and <literal>b</literal>,
134             such that <literal>M=a(ka,:)</literal> and <literal>M=b(kb,:)</literal>.
135         </para>
136         <para>
137             <literal>intersect(a,b,"c")</literal> or <literal>intersect(a,b,2)</literal> does
138             the same for columns.
139         </para>
140         </refsect3>
141     </refsection>
142     <refsection>
143         <title>Examples</title>
144         <programlisting role="example"><![CDATA[
145 A = grand(3, 3, "uin", 0, 9)
146 B = grand(2, 4, "uin", 0, 9)
147 intersect(A, B)
148 [N, ka, kb] = intersect(A,B);
149 ka, kb
150  ]]></programlisting>
151     <screen><![CDATA[
152 --> A = grand(3, 3, "uin", 0, 9)
153  A  =
154    0.   6.   4.
155    6.   6.   6.
156    2.   7.   9.
157
158 --> B = grand(2, 4, "uin", 0, 9)
159  B  =
160    1.   8.   0.   2.
161    6.   2.   2.   1.
162
163 --> intersect(A, B)
164  ans  =
165    0.   2.   6.
166
167 --> [N, ka, kb] = intersect(A,B);
168 --> ka, kb
169  ka  =
170    1.   3.   2.
171  kb  =
172    5.   4.   2.
173 ]]></screen>
174     <para>
175         In the above example, note that 6 is met four times in A, at indices [2 4 5 8].
176         Only the minimal index 2 is returned in ka. Same situation for 2 in B.
177     </para>
178     <para/>
179     <para>
180     NaN values can never be in the result:
181     </para>
182     <programlisting role="example"><![CDATA[
183 %nan == %nan
184 intersect([1 -2 %nan 3 6], [%nan 1:3])
185  ]]></programlisting>
186     <screen><![CDATA[
187 --> %nan == %nan
188  ans  =
189   F
190
191 --> intersect([1 -2 %nan 3 6], [%nan 1:3])
192  ans  =
193    1.   3.
194 ]]></screen>
195     <para/>
196     <para>
197         intersect() can also process some characters or some texts. Since Scilab is great with UTF
198         characters, here is an example with some Arabic contents, getting characters present in
199         both sentences:
200     </para>
201         <programlisting role="example"><![CDATA[
202 A = strsplit("هو برنامج علمي كبير ""Scilab""")'
203 B = strsplit("فهو حر ومفتوح")'
204 intersect(A,B)
205  ]]></programlisting>
206     <screen><![CDATA[
207 --> A = strsplit("هو برنامج علمي كبير ""Scilab""")'
208  A  =
209 !ه  و     ب  ر  ن  ا  م  ج     ع  ل  م  ي     ك  ب  ي  ر     "  S  c  i  l  a  b  "  !
210
211 --> B = strsplit("فهو حر ومفتوح")'
212  B  =
213 !ف  ه  و     ح  ر     و  م  ف  ت  و  ح  !
214
215 --> intersect(A,B)
216  ans  =
217 !   ر  م  ه  و  !
218 ]]></screen>
219     <para/>
220     <para>
221         Column-wise or Row-wise processing of two matrices: Here we process 2 matrices of
222         signed 1-byte integers, and get the common columns:
223     </para>
224     <programlisting role="example"><![CDATA[
225 A = int8(grand(3,5,"uin",0,1))
226 B = int8(grand(3,9,"uin",0,1))
227 [M,ka,kb] = intersect(A, B, "c");
228 M, ka, kb
229  ]]></programlisting>
230     <screen><![CDATA[
231 --> A = int8(grand(3,5,"uin",0,1))
232  A  =
233   0  0  1  1  1
234   0  0  1  1  0
235   0  0  0  0  1
236
237 --> B = int8(grand(3,9,"uin",0,1))
238  B  =
239   1  0  1  1  1  0  1  1  1
240   1  0  0  1  1  1  0  0  0
241   1  0  1  0  1  1  1  0  0
242
243 --> [M,ka,kb] = intersect(A, B, "c");
244 --> M, ka, kb
245  M  =
246   0  1  1
247   0  0  1
248   0  1  0
249
250  ka  =
251    1.   5.   3.
252
253  kb  =
254    2.   3.   4.
255 ]]></screen>
256     </refsection>
257     <refsection role="see also">
258         <title>See also</title>
259         <simplelist type="inline">
260             <member>
261                 <link linkend="members">members</link>
262             </member>
263             <member>
264                 <link linkend="unique">unique</link>
265             </member>
266             <member>
267                 <link linkend="gsort">gsort</link>
268             </member>
269             <member>
270                 <link linkend="union">union</link>
271             </member>
272         </simplelist>
273     </refsection>
274 </refentry>