* Bug 15841 fixed: intersect() now accepts sparse
[scilab.git] / scilab / modules / elementary_functions / help / fr_FR / 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) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - 2020 - 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="intersect" xml:lang="fr">
20     <refnamediv>
21         <refname>intersect</refname>
22         <refpurpose>
23             éléments, lignes, ou colonnes communs aux 2 tableaux d'entrée, sans doublon
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntaxe</title>
28         <synopsis>
29             M = intersect(a, b)
30             M = intersect(a, b, orient)
31             [M, ka] = intersect(..)
32             [M, ka, kb] = intersect(..)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>a, b</term>
40                 <listitem>
41                     vecteurs, matrices ou hypermatrices de booléens, d'entiers encodés, de nombres
42                     réels ou complexes, ou de texte. <varname>a</varname> et <varname>b</varname>
43                     doivent être du même type de données, mais ont des tailles indépendantes.
44                     Pour les données texte, les caractères UTF sont admis.
45                     Les matrices creuses booléennes ou numériques sont acceptées :
46                     <varname>a</varname> ou <varname>b</varname> ou les deux peuvent être creuses.
47                     <para/>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>orient</term>
52                 <listitem>
53                     indicateur de traitement par colonnes ou lignes. Valeurs possibles :
54                     1 ou "r", 2 ou "c". Ne peut pas être utilisé lorsque <varname>a</varname>
55                     ou/et <varname>b</varname> est une hypermatrice.
56                     <para/>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>M</term>
61                 <listitem>
62                     <para>
63                         Matrice du type de <varname>a</varname> et <varname>b</varname>.
64                         <itemizedlist>
65                             <listitem>
66                                 Sans <varname>orient</varname>: <varname>M</varname> est un vecteur
67                                 ligne.
68                             </listitem>
69                             <listitem>
70                                 Avec <literal>orient="r"|1</literal>: <varname>M</varname> est une
71                                 matrice empilant les lignes communes à <varname>a</varname> et
72                                 <varname>b</varname>.
73                             </listitem>
74                             <listitem>
75                                 Avec <literal>orient="c"|2</literal>: <varname>M</varname> est une
76                                 matrice concaténant les colonnes communes à <varname>a</varname> et
77                                 <varname>b</varname>.
78                             </listitem>
79                         </itemizedlist>
80                     </para>
81                     <para>
82                         <varname>M</varname> est creuse dés que <varname>a</varname> ou
83                         <varname>b</varname> est creuse et aucune n'est vide.
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>ka</term>
89                 <listitem>
90                     Vecteur ligne dense d'indices dans <varname>a</varname>.
91                     <para/>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>kb</term>
96                 <listitem>
97                     Vecteur ligne dense d'indices dans <varname>b</varname>.
98                     <para/>
99                 </listitem>
100             </varlistentry>
101         </variablelist>
102     </refsection>
103     <refsection>
104         <title>Description</title>
105         <para>
106             <literal>intersect(a,b)</literal> produit un vecteur ligne des éléments dédoublonnés
107             présents à la fois dans les tableaux <literal>a</literal> et <literal>b</literal>,
108             triés en ordre croissant
109             <itemizedlist>
110                 <listitem>
111                     pour les nombres complexes : par modules croissants, puis par phases croissantes.
112                 </listitem>
113                 <listitem>
114                     pour le texte : par ordre alphabétique.
115                 </listitem>
116             </itemizedlist>
117         </para>
118         <warning>
119             Deux éléments NaN étant toujours considérés comme différents, NaN ou les lignes ou
120             colonnes en contenant ne seront jamais présents dans le résultat <literal>M</literal>.
121         </warning>
122         <para>
123             <literal>[M, ka, kb] = intersect(a,b)</literal> fournit en outre les vecteurs lignes
124             <literal>ka</literal> et <literal>kb</literal> des indices dans <literal>a</literal>
125             et <literal>b</literal> des éléments communs rencontrés à leur première position,
126             tels que <literal>M=a(ka)</literal> and <literal>M=b(kb)</literal>.
127         </para>
128         <refsect3>
129             <title>Lignes ou colonnes en commun</title>
130         <para>
131             Lorsque l'option <varname>orient</varname> est utilisée, la comparaison entre
132             <literal>a</literal> et <literal>b</literal> est réalisée en considérant leurs lignes
133             ou leurs colonnes dans leur entier.
134         </para>
135         <para>
136             <literal>intersect(a,b,"r")</literal> ou <literal>intersect(a,b,1)</literal> fournira
137             la matrice des lignes (sans doublons) présentes à la fois dans <literal>a</literal> et
138             dans <literal>b</literal>, triées en ordre lexicographique croissant.
139             Lorsque <literal>a</literal> et <literal>b</literal> n'ont pas le même nombre de
140             colonnes, [] est retourné sans comparer aucun élément.
141         </para>
142         <para>
143             <literal>[M,ka,kb]=intersect(a,b,"r")</literal> fournit en outre les vecteurs
144             <literal>ka</literal> et <literal>kb</literal> des indices minimaux des lignes communes,
145             indices respectivement dans <literal>a</literal> dans <literal>b</literal>. On a alors
146             <literal>M=a(ka,:)</literal> et <literal>M=b(kb,:)</literal>.
147         </para>
148         <para>
149             <literal>intersect(a,b,"c")</literal> ou <literal>intersect(a,b,2)</literal> réalise
150             la même chose sur les colonnes.
151         </para>
152         </refsect3>
153     </refsection>
154     <refsection>
155         <title>Exemples</title>
156         <programlisting role="example"><![CDATA[
157 A = grand(3, 3, "uin", 0, 9)
158 B = grand(2, 4, "uin", 0, 9)
159 intersect(A, B)
160 [N, ka, kb] = intersect(A,B);
161 ka, kb
162  ]]></programlisting>
163     <screen><![CDATA[
164 --> A = grand(3, 3, "uin", 0, 9)
165  A  =
166    0.   6.   4.
167    6.   6.   6.
168    2.   7.   9.
169
170 --> B = grand(2, 4, "uin", 0, 9)
171  B  =
172    1.   8.   0.   2.
173    6.   2.   2.   1.
174
175 --> intersect(A, B)
176  ans  =
177    0.   2.   6.
178
179 --> [N, ka, kb] = intersect(A,B);
180 --> ka, kb
181  ka  =
182    1.   3.   2.
183  kb  =
184    5.   4.   2.
185 ]]></screen>
186     <para>
187         Dans l'exemple ci-dessus, on notera que 6 est présent quatre fois dans A, aux indices [2 4 5 8].
188         Seule la position d'indice minimal 2 est donnée dans ka. Même situation pour 2 dans B.
189     </para>
190     <para/>
191     <para>
192     La valeur NaN (Not-a-Number) ne peut jamais figurer dans le résultat :
193     </para>
194     <programlisting role="example"><![CDATA[
195 %nan == %nan
196 intersect([1 -2 %nan 3 6], [%nan 1:3])
197  ]]></programlisting>
198     <screen><![CDATA[
199 --> %nan == %nan
200  ans  =
201   F
202
203 --> intersect([1 -2 %nan 3 6], [%nan 1:3])
204  ans  =
205    1.   3.
206 ]]></screen>
207     <para/>
208     <para>
209         intersect() peut aussi traiter des caractères ou du texte. Scilab sait traiter les textes
210         encodés en UTF. Voici un exemple avec du texte en arabe, afin d'obtenir les caractères
211         arabes communs à deux phrases :
212     </para>
213         <programlisting role="example"><![CDATA[
214 A = strsplit("هو برنامج علمي كبير ""Scilab""")'
215 B = strsplit("فهو حر ومفتوح")'
216 intersect(A,B)
217  ]]></programlisting>
218     <screen><![CDATA[
219 --> A = strsplit("هو برنامج علمي كبير ""Scilab""")'
220  A  =
221 !ه  و     ب  ر  ن  ا  م  ج     ع  ل  م  ي     ك  ب  ي  ر     "  S  c  i  l  a  b  "  !
222
223 --> B = strsplit("فهو حر ومفتوح")'
224  B  =
225 !ف  ه  و     ح  ر     و  م  ف  ت  و  ح  !
226
227 --> intersect(A,B)
228  ans  =
229 !   ر  م  ه  و  !
230 ]]></screen>
231     <para/>
232     <para>
233         Lignes ou colonnes communes à deux matrices : l'exemple suivant extrait les colonnes communes
234         à deux matrices d'entiers signés encodés sur un octet :
235     </para>
236     <programlisting role="example"><![CDATA[
237 A = int8(grand(3,5,"uin",0,1))
238 B = int8(grand(3,9,"uin",0,1))
239 [M,ka,kb] = intersect(A, B, "c");
240 M, ka, kb
241  ]]></programlisting>
242     <screen><![CDATA[
243 --> A = int8(grand(3,5,"uin",0,1))
244  A  =
245   0  0  1  1  1
246   0  0  1  1  0
247   0  0  0  0  1
248
249 --> B = int8(grand(3,9,"uin",0,1))
250  B  =
251   1  0  1  1  1  0  1  1  1
252   1  0  0  1  1  1  0  0  0
253   1  0  1  0  1  1  1  0  0
254
255 --> [M,ka,kb] = intersect(A, B, "c");
256 --> M, ka, kb
257  M  =
258   0  1  1
259   0  0  1
260   0  1  0
261
262  ka  =
263    1.   5.   3.
264
265  kb  =
266    2.   3.   4.
267 ]]></screen>
268     <para/>
269     <para>
270         Pour des booléens, <literal>intersect()</literal> est utile essentiellement avec l'option
271         "r" ou "c". Voici un exemple avec une matrice booléenne creuse :
272     </para>
273     <programlisting role="example"><![CDATA[
274 [F, T] = (%f, %t);
275 A = [F F T F T F ; T F F T T T ; T T F T F F]
276 B = [F T F T F F ; T F F F T F ; F T F F T F]
277 [M,ka,kb] = intersect(A, sparse(B), "c");
278 issparse(M), full(M), ka, kb
279  ]]></programlisting>
280     <screen><![CDATA[
281 --> A = [F F T F T F ; T F F T T T ; T T F T F F]
282  A  =
283   F F T F T F
284   T F F T T T
285   T T F T F F
286
287 --> B = [F T F T F F ; T F F F T F ; F T F F T F]
288  B  =
289   F T F T F F
290   T F F F T F
291   F T F F T F
292
293 --> [M,ka,kb] = intersect(A, sparse(B), "c");
294 --> issparse(M), full(M), ka, kb
295  ans  =
296   T
297
298  ans  =
299   F F T
300   T T F
301   F T F
302
303  ka  =
304    6.   1.   3.
305
306  kb  =
307    1.   5.   4.
308 ]]></screen>
309     </refsection>
310     <refsection role="see also">
311         <title>Voir aussi</title>
312         <simplelist type="inline">
313             <member>
314                 <link linkend="members">members</link>
315             </member>
316             <member>
317                 <link linkend="unique">unique</link>
318             </member>
319             <member>
320                 <link linkend="gsort">gsort</link>
321             </member>
322             <member>
323                 <link linkend="union">union</link>
324             </member>
325         </simplelist>
326     </refsection>
327     <refsection role="history">
328         <title>Historique</title>
329         <revhistory>
330             <revision>
331                 <revnumber>6.1.0</revnumber>
332                 <revdescription>
333                     Nombres complexes désormais acceptés.
334                 </revdescription>
335             </revision>
336             <revision>
337                 <revnumber>6.1.1</revnumber>
338                 <revdescription>
339                     Matrices creuses numériques ou booléennes désormais acceptées.
340                 </revdescription>
341             </revision>
342         </revhistory>
343     </refsection>
344 </refentry>