* Bugs 15866 & 15867 fixed: setdiff() + 'r'|'c' & integers
[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"><emphasis role="bold">none</emphasis></td>
140                     <td colspan="2" align="center"><emphasis role="bold">"r"</emphasis></td>
141                     <td colspan="2" align="center"><emphasis role="bold">"c"</emphasis></td>
142                 </tr>
143                 <tr>
144                     <th>a ↓</th><th>v</th><th>ka</th><th>v</th><th>ka</th><th>v</th><th>ka</th>
145                 </tr>
146                 <tr>
147                     <td align="right"><emphasis role="bold">row</emphasis></td>
148                     <td>row</td><td>row</td>
149                     <td>row</td><td>scal</td>
150                     <td>row</td><td>row</td>
151                 </tr>
152                 <tr>
153                     <td align="right"><emphasis role="bold">column</emphasis></td>
154                     <td>col</td><td>col</td>
155                     <td>col</td><td>col</td>
156                     <td>col</td><td>scal</td>
157                 </tr>
158                 <tr>
159                     <td align="right"><emphasis role="bold">matrix</emphasis></td>
160                     <td>col</td><td>col</td>
161                     <td>mat</td><td>col</td>
162                     <td>mat</td><td>row</td>
163                 </tr>
164                 <tr>
165                     <td align="right"><emphasis role="bold">hypermatrix</emphasis></td>
166                     <td>col</td><td>col</td>
167                     <td>mat</td><td>col</td>
168                     <td>mat</td><td>row</td>
169                 </tr>
170                 <tr align="center">
171                     <td align="right"><emphasis role="bold">scalar</emphasis></td>
172                     <td>scal</td><td>scal</td>
173                     <td>scal</td><td>scal</td>
174                     <td>scal</td><td>scal</td>
175                 </tr>
176             </table>
177         </para>
178         <para>
179             <literal>v</literal> and <literal>ka</literal> become empty <literal>[]</literal>
180             if <literal>a</literal> is empty (whatever is <literal>b</literal>), or if all
181             <literal>a</literal> elements are in <literal>b</literal>.
182         </para>
183     </refsection>
184     <refsection>
185         <title>Examples</title>
186         <para>
187             <emphasis role="bold">Example #1:</emphasis>
188         </para>
189         <programlisting role="example"><![CDATA[
190 a = grand(1, 10,"uin", 0, 9)
191 b = grand(2, 4, "uin", 0, 9)
192 [d, k] = setdiff(a, b);
193 d, k
194  ]]></programlisting>
195     <screen><![CDATA[
196 --> a = grand(1, 10,"uin", 0, 9)
197  a  =
198    2.   2.   4.   5.   4.   1.   9.   5.   8.   3.
199
200 --> b = grand(2, 4, "uin", 0, 9)
201  b  =
202    5.   0.   9.   9.
203    5.   6.   0.   4.
204
205 --> [d, k] = setdiff(a, b);
206 --> d, k
207  d  =
208    1.   2.   3.   8.
209
210  k  =
211    6.   1.   10.   9.
212  ]]></screen>
213         <para>
214             <emphasis role="bold">Example #2: column-wise processing</emphasis>
215         </para>
216         <programlisting role="example"><![CDATA[
217 a = grand(2, 7,"uin", 0, 3)
218 b = grand(2, 10, "uin", 0, 3)
219 [d, k] = setdiff(a, b, "c");
220 d, k
221  ]]></programlisting>
222     <screen><![CDATA[
223 --> a = grand(2, 7,"uin", 0, 3)
224  a  =
225    0.   1.   0.   2.   3.   0.   2.
226    2.   2.   2.   1.   0.   1.   2.
227
228 --> b = grand(2, 10, "uin", 0, 3)
229  b  =
230    1.   1.   3.   1.   1.   1.   3.   0.   2.   0.
231    3.   3.   2.   2.   0.   0.   1.   0.   1.   0.
232
233 --> [d, k] = setdiff(a, b, "c");
234 --> d, k
235  d  =
236    0.   0.   2.   3.
237    1.   2.   2.   0.
238
239  k  =
240    6.   1.   7.   5.
241  ]]></screen>
242         <para>
243             <emphasis role="bold">Example #3: with some text</emphasis>
244         </para>
245         <programlisting role="example"><![CDATA[
246 v1 = tokens("ab  ca  ba  bb  ca  cb  ba  aa  cc  bc  ac  aa")'
247 v2 = tokens("cc  ac  ca  bb  ac  bc  ab")'
248 [r, k] = setdiff(v1, v2);
249 r, k
250 ]]></programlisting>
251     <screen><![CDATA[
252 --> v1 = tokens("ab  ca  ba  bb  ca  cb  ba  aa  cc  bc  ac  aa")'
253  v1  =
254 !ab  ca  ac  bb  ca  cb  ba  aa  cc  bc  ac  aa  !
255
256 --> v2 = tokens("cc  ac  ca  bb  ac  bc  ab")'
257  v2  =
258 !cc  ac  ca  bb  ac  bc  ab  !
259
260 --> [r, k] = setdiff(v1, v2);
261 --> r, k
262  r  =
263 !aa  ba  cb  !
264
265  k  =
266    8.   3.   6.
267 ]]></screen>
268     </refsection>
269     <refsection role="see also">
270         <title>See also</title>
271         <simplelist type="inline">
272             <member>
273                 <link linkend="unique">unique</link>
274             </member>
275             <member>
276                 <link linkend="union">union</link>
277             </member>
278             <member>
279                 <link linkend="members">members</link>
280             </member>
281             <member>
282                 <link linkend="vertorfind">vectorfind</link>
283             </member>
284         </simplelist>
285     </refsection>
286     <refsection role="history">
287         <title>History</title>
288         <revhistory>
289             <revision>
290                 <revnumber>&lt; 5.0</revnumber>
291                 <revdescription>
292                     Function introduced.
293                 </revdescription>
294             </revision>
295             <revision>
296                 <revnumber>6.0.2</revnumber>
297                 <revdescription>
298                     Option "r" | "c" added, including for hypermatrices.
299                 </revdescription>
300             </revision>
301         </revhistory>
302     </refsection>
303 </refentry>