4a40173aae9e0a048dea3dac5405edaa5b21e301
[scilab.git] / scilab / modules / elementary_functions / help / en_US / setoperations / setdiff.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) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="setdiff" xml:lang="en">
20     <refnamediv>
21         <refname>setdiff</refname>
22         <refpurpose>
23             returns elements or rows or columns of an array that do not belong to another one
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             v = setdiff(a, b)
30             v = setdiff(a, b, orien)
31             [v, ka] = setdiff(..)
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Arguments</title>
36         <variablelist>
37             <varlistentry>
38                 <term>a, b</term>
39                 <listitem>
40                     <para>
41                         vectors, matrices or hypermatrices of real numbers or encoded integers or
42                         strings. Both must have the same data types (and integer types).
43                     </para>
44                     <para>
45                         If the option <literal>orien="r"</literal> is used, <literal>a</literal>
46                         and <literal>b</literal> must have the same number of columns.
47                         If the <literal>orien="c"</literal> is used, they must have the same
48                         number of rows.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>orien</term>
54                 <listitem>
55                     oriented processing:
56                     <itemizedlist>
57                         <listitem>
58                             <literal>"r"</literal>: rows of
59                             <literal>a</literal> are searched among <literal>b</literal> ones.
60                         </listitem>
61                         <listitem>
62                             <literal>"c"</literal>: columns of
63                             <literal>a</literal> are searched among <literal>b</literal> ones.
64                         </listitem>
65                         <listitem>
66                             no orien: elements of <literal>a</literal> are searched among
67                             <literal>b</literal> ones.
68                         </listitem>
69                     </itemizedlist>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>v</term>
74                 <listitem>
75                     <itemizedlist>
76                         <listitem>
77                             sorted vector of <literal>a</literal>'s components that are not in
78                             <literal>b</literal>.
79                         </listitem>
80                         <listitem>
81                             <literal>orien="r"</literal>: matrix of rows of <literal>a</literal>
82                             that are not in <literal>b</literal>, sorted in lexicographic order.
83                         </listitem>
84                         <listitem>
85                             <literal>orien="c"</literal>: matrix of columns of <literal>a</literal>
86                             that are not in <literal>b</literal>, sorted in lexicographic order.
87                         </listitem>
88                     </itemizedlist>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>ka</term>
93                 <listitem>
94                     <para>
95                         vector of linear indices of selected  <literal>a</literal>'s components,
96                         rows, or columns, such that
97                         <itemizedlist>
98                             <listitem>
99                                 <literal>v = a(ka)</literal>, or
100                             </listitem>
101                             <listitem>
102                                 <literal>v = a(ka,:)</literal> (<literal>orien="r"</literal>), or
103                             </listitem>
104                             <listitem>
105                                 <literal>v = a(:,ka)</literal> (<literal>orien="c"</literal>)
106                             </listitem>
107                         </itemizedlist>
108                     </para>
109                 </listitem>
110             </varlistentry>
111         </variablelist>
112     </refsection>
113     <refsection>
114         <title>Description</title>
115         <para>
116             <literal>setdiff(a, b,..)</literal> computes and returns the elements or rows or columns
117             of <literal>a</literal> that are NOT in <literal>b</literal>.
118         </para>
119         <para>
120             All duplicates (elements or rows or columns) are removed from <literal>a</literal> and
121             from <literal>b</literal> before processing.
122         </para>
123         <para>
124             If <literal>a</literal> is an hypermatrix and the <literal>"r"</literal> option is used,
125             <literal>a</literal> is replaced with the matrix of all its rows over all its higher
126             dimensions, before processing.
127             Same thing if <literal>b</literal> is an hypermatrix.
128             If the <literal>"c"</literal> option is used, <literal>a</literal> or/and
129             <literal>"b"</literal> are replaced with the respective matrices of all their columns.
130         </para>
131         <para>
132             The format of results is presented in the following table, according to the shape of
133             <literal>a</literal> and the <literal>orien</literal> option. In all cases, if all
134             entities of <literal>a</literal> are in <literal>b</literal>,
135             <literal>[]</literal> is returned for <literal>v</literal> as for <literal>ka</literal>:
136             <table>
137                 <tr>
138                     <th align="right">orien →</th>
139                     <td colspan="2" align="center">
140                         <emphasis role="bold">none</emphasis>
141                     </td>
142                     <td colspan="2" align="center">
143                         <emphasis role="bold">"r"</emphasis>
144                     </td>
145                     <td colspan="2" align="center">
146                         <emphasis role="bold">"c"</emphasis>
147                     </td>
148                 </tr>
149                 <tr>
150                     <th>a ↓</th><th>v</th><th>ka</th><th>v</th><th>ka</th><th>v</th><th>ka</th>
151                 </tr>
152                 <tr>
153                     <td align="right">
154                         <emphasis role="bold">row</emphasis>
155                     </td>
156                     <td>row</td><td>row</td>
157                     <td>row</td><td>scal</td>
158                     <td>row</td><td>row</td>
159                 </tr>
160                 <tr>
161                     <td align="right">
162                         <emphasis role="bold">column</emphasis>
163                     </td>
164                     <td>col</td><td>col</td>
165                     <td>col</td><td>col</td>
166                     <td>col</td><td>scal</td>
167                 </tr>
168                 <tr>
169                     <td align="right">
170                         <emphasis role="bold">matrix</emphasis>
171                     </td>
172                     <td>col</td><td>col</td>
173                     <td>mat</td><td>col</td>
174                     <td>mat</td><td>row</td>
175                 </tr>
176                 <tr>
177                     <td align="right">
178                         <emphasis role="bold">hypermatrix</emphasis>
179                     </td>
180                     <td>col</td><td>col</td>
181                     <td>mat</td><td>col</td>
182                     <td>mat</td><td>row</td>
183                 </tr>
184                 <tr align="center">
185                     <td align="right">
186                         <emphasis role="bold">scalar</emphasis>
187                     </td>
188                     <td>scal</td><td>scal</td>
189                     <td>scal</td><td>scal</td>
190                     <td>scal</td><td>scal</td>
191                 </tr>
192             </table>
193         </para>
194         <para>
195             <literal>v</literal> and <literal>ka</literal> become empty <literal>[]</literal>
196             if <literal>a</literal> is empty (whatever is <literal>b</literal>), or if all
197             <literal>a</literal> elements are in <literal>b</literal>.
198         </para>
199     </refsection>
200     <refsection>
201         <title>Examples</title>
202         <para>
203             <emphasis role="bold">Example #1:</emphasis>
204         </para>
205         <programlisting role="example"><![CDATA[
206 a = grand(1, 10,"uin", 0, 9)
207 b = grand(2, 4, "uin", 0, 9)
208 [d, k] = setdiff(a, b);
209 d, k
210  ]]></programlisting>
211         <screen><![CDATA[
212 --> a = grand(1, 10,"uin", 0, 9)
213  a  =
214    2.   2.   4.   5.   4.   1.   9.   5.   8.   3.
215
216 --> b = grand(2, 4, "uin", 0, 9)
217  b  =
218    5.   0.   9.   9.
219    5.   6.   0.   4.
220
221 --> [d, k] = setdiff(a, b);
222 --> d, k
223  d  =
224    1.   2.   3.   8.
225
226  k  =
227    6.   1.   10.   9.
228  ]]></screen>
229         <para>
230             <emphasis role="bold">Example #2: column-wise processing</emphasis>
231         </para>
232         <programlisting role="example"><![CDATA[
233 a = grand(2, 7,"uin", 0, 3)
234 b = grand(2, 10, "uin", 0, 3)
235 [d, k] = setdiff(a, b, "c");
236 d, k
237  ]]></programlisting>
238         <screen><![CDATA[
239 --> a = grand(2, 7,"uin", 0, 3)
240  a  =
241    0.   1.   0.   2.   3.   0.   2.
242    2.   2.   2.   1.   0.   1.   2.
243
244 --> b = grand(2, 10, "uin", 0, 3)
245  b  =
246    1.   1.   3.   1.   1.   1.   3.   0.   2.   0.
247    3.   3.   2.   2.   0.   0.   1.   0.   1.   0.
248
249 --> [d, k] = setdiff(a, b, "c");
250 --> d, k
251  d  =
252    0.   0.   2.   3.
253    1.   2.   2.   0.
254
255  k  =
256    6.   1.   7.   5.
257  ]]></screen>
258         <para>
259             <emphasis role="bold">Example #3: with some text</emphasis>
260         </para>
261         <programlisting role="example"><![CDATA[
262 v1 = tokens("ab  ca  ba  bb  ca  cb  ba  aa  cc  bc  ac  aa")'
263 v2 = tokens("cc  ac  ca  bb  ac  bc  ab")'
264 [r, k] = setdiff(v1, v2);
265 r, k
266 ]]></programlisting>
267         <screen><![CDATA[
268 --> v1 = tokens("ab  ca  ba  bb  ca  cb  ba  aa  cc  bc  ac  aa")'
269  v1  =
270 !ab  ca  ac  bb  ca  cb  ba  aa  cc  bc  ac  aa  !
271
272 --> v2 = tokens("cc  ac  ca  bb  ac  bc  ab")'
273  v2  =
274 !cc  ac  ca  bb  ac  bc  ab  !
275
276 --> [r, k] = setdiff(v1, v2);
277 --> r, k
278  r  =
279 !aa  ba  cb  !
280
281  k  =
282    8.   3.   6.
283 ]]></screen>
284     </refsection>
285     <refsection role="see also">
286         <title>See also</title>
287         <simplelist type="inline">
288             <member>
289                 <link linkend="unique">unique</link>
290             </member>
291             <member>
292                 <link linkend="union">union</link>
293             </member>
294             <member>
295                 <link linkend="members">members</link>
296             </member>
297             <member>
298                 <link linkend="vectorfind">vectorfind</link>
299             </member>
300         </simplelist>
301     </refsection>
302     <refsection role="history">
303         <title>History</title>
304         <revhistory>
305             <revision>
306                 <revnumber>&lt; 5.0</revnumber>
307                 <revdescription>
308                     Function introduced.
309                 </revdescription>
310             </revision>
311             <revision>
312                 <revnumber>6.0.2</revnumber>
313                 <revdescription>
314                     Option "r" | "c" added, including for hypermatrices.
315                 </revdescription>
316             </revision>
317         </revhistory>
318     </refsection>
319 </refentry>