Elementary_functions: members() improved
[scilab.git] / scilab / modules / elementary_functions / help / fr_FR / setoperations / members.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) 2013 - Samuel GOUGEON
5  * Copyright (C) 2009 - Université du Maine - Samuel GOUGEON
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="members" xml:lang="fr">
15     <refnamediv>
16         <refname>members</refname>
17         <refpurpose>dénombre (et localise) dans un tableau chaque élément ou ligne ou colonne d'un autre tableau
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Séquence d'appel</title>
22         <synopsis>
23             [nb [,loc]] = members(N, H)
24             [nb [,loc]] = members(N, H, "last")
25             [nb [,loc]] = members(N, H, "rows"|"cols")
26             [nb [,loc]] = members(N, H, "rows"|"cols", "last")
27             [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle")
28             [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle", "last")
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Paramètres</title>
33         <variablelist>
34             <varlistentry>
35                 <term>N</term>
36                 <listitem>
37                     <para>
38                         Matrice ou hypermatrice dont les éléments, rangées ou colonnes doivent être recherchés. Il peut s'agir de booléens, d'entiers encodés, de nombres décimaux réels ou complexes, de polynômes ou de textes. En mode "rows" ou "cols", l'hypermatrice n'est pas acceptée. Un élément donné (ou une rangée ou colonne) peut apparaitre plusieurs fois dans <literal>N</literal>.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>H</term>
44                 <listitem>
45                     <para>
46                         Matrice ou hypermatrice scrutée, de même type que <literal>N</literal>. En mode "rows" / "cols", l'hypermatrice n'est pas acceptée, et <literal>N</literal> et <literal>H</literal> doivent avoir le même nombre de colonnes / lignes.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>Options :</term>
52                 <listitem>
53                     <para>Une à 3 options peuvent être indiquées après H, sans ordre particulier :
54                         <variablelist>
55                             <varlistentry>
56                                 <term>"last"</term>
57                                 <listitem>
58                                     <para>
59                                         Lorsque la localisation dans <literal>H</literal> des éléments de <literal>N</literal> est retournée via le paramètre de sortie <literal>loc</literal>, par défaut les positions des 1ères occurences dans <literal>H</literal> sont retournées, élément par élément de N. Si <literal>"last"</literal> est indiqué, les positions retournées sont celles des dernières occurences dans <literal>H</literal>.
60                                     </para>
61                                 </listitem>
62                             </varlistentry>
63                             <varlistentry>
64                                 <term>"rows", "cols"</term>
65                                 <listitem>
66                                     <para>
67                                         Par défaut, chaque élément individuel <literal>N(i, j, ..)</literal> de <literal>N</literal> est recherché dans <literal>H</literal>. Si <literal>"rows"</literal> est indiquée, chaque rangée de <literal>N</literal> est recherchée parmi les rangées de <literal>H</literal>. De même, si <literal>"cols"</literal> est indiquée, chaque colonne de <literal>N</literal> est recherchée parmi les colonnes de <literal>H.</literal>.
68                                     </para>
69                                 </listitem>
70                             </varlistentry>
71                             <varlistentry>
72                                 <term>"shuffle"</term>
73                                 <listitem>
74                                     <para>
75                                         En mode <literal>"rows"</literal> ou <literal>"cols"</literal>, par défaut l'ordre des éléments d'une rangée ou d'une colonne est pris en compte : par exemple, <literal>[ 7 3 5 ]</literal> dans <literal>N</literal> et <literal>[ 3 5 7]</literal> dans <literal>H</literal> ne correspondront pas. Lorsque l'option <literal>"shuffle"</literal> est utilisée, toute permutation de --disons--<literal>[3 5 7]</literal> sera reconnue dans H comme correspondant à la rangée <literal>[3 5 7]</literal> dans <literal>N</literal>. Cette option est ignorée pour les polynômes.
76                                     </para>
77                                 </listitem>
78                             </varlistentry>
79                         </variablelist>
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>nb</term>
85                 <listitem>
86                     <para>
87                         En mode normal : <literal>nb(i, j, ..)</literal> (décimaux) retourne le nombre d'occurences dans <literal>H</literal> de <literal>N(i, j, ..)</literal>. <literal>nb</literal> et <literal>N</literal> ont le même format. Si <literal>H</literal> est vide [], une matrice de zéros est retournée. Si <literal>N</literal> est vide, la matrice vide <literal>[]</literal> est retournée.
88                     </para>
89                     <para>
90                         En mode <literal>"rows"</literal> ou <literal>"cols"</literal> : <literal>nb</literal> est un vecteur ligne de décimaux avec autant d'élements que <literal>N</literal> a de rangées ou colonnes. <literal>nb(i)</literal> retourne le nombre d'occurences dans <literal>H(1:$, :)</literal> de <literal>N(i, :)</literal> (ou de <literal>N(:, i)</literal> dans <literal>H(:, 1:$)</literal> ).
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>loc</term>
96                 <listitem>
97                     <para>
98                         En mode normal : <literal>loc</literal> et <literal>N</literal> ont le même format. <literal>loc(i, j, ..)</literal> retourne le n°(linéarisé) dans <literal>H</literal> le plus petit auquel <literal>N(i, j, ..)</literal> advient : <literal>H(loc(i, j, ..))==N(i, j, ..)</literal>. Si l'option <literal>"last"</literal> est utilisée, le n° le plus grand vérifiant la même condition est retourné à la place. Si <literal>N(i, j, ..)</literal> n'est pas présent dans <literal>H</literal>, <literal>loc(i, j, ..)</literal> est mis à <literal>0</literal>.
99                     </para>
100                     <para>
101                         En mode <literal>"rows"</literal> ou <literal>"cols"</literal> : <literal>loc</literal> est un vecteur ligne de décimaux, avec autant d'éléments que <literal>N</literal> a respectivement de rangées ou de colonnes. <literal>loc(i)</literal> retourne le n° de la 1ère ligne <literal>H(loc(i), :)</literal> identifiable à <literal>N(i, :)</literal> (ou le n° de la 1ère colonne <literal>H(:, loc(i))</literal> identifiable à <literal>N(:, i)</literal>). Si l'option <literal>"shuffle"</literal> est en outre utilisée, l'ordre des éléments de <literal>N(i, :)</literal> est ignoré et toutes les permutations de <literal>N(i, :)</literal> identifiables en rangées de <literal>H</literal> sont considérées.
102                     </para>
103                 </listitem>
104             </varlistentry>
105         </variablelist>
106     </refsection>
107     <refsection>
108         <title>Description</title>
109         <para>
110             <literal>nb = members(N, H [,"rows"|"cols"])</literal> retourne le nombre d'occurences de chaque élément ou rangée ou colonne de <literal>N</literal> identifiables dans <literal>H</literal>. Si aucune correspondance n'est trouvée, 0 est retourné pour le composant considéré.
111             La position dans <literal>H</literal> de la 1ère (par défaut) ou de la dernière (avec <literal>"last"</literal>) occurence des <literal>N(i, j, ...)</literal> peut être obtenue via la seconde variable de sortie <literal>loc</literal>.
112             Si des rangées ou colonnes correspondantes sont recherchées, l'ordre de leurs éléments peut être ignoré en utilisant l'option <literal>"shuffle"</literal>.
113         </para>
114         <para>
115             Les valeurs spéciales <literal>%inf</literal> et <literal>-%inf</literal> sont admises dans <literal>N</literal> comme dans <literal>H</literal>.
116             <literal>%nan</literal> est toujours admis dans <literal>N</literal>, mais pas dans <literal>H</literal> en mode normal.
117         </para>
118         <para>
119             En mode normal (élément par élément), members(..) utilise la fonction <link type="scilab" linkend="scilab.help/dsearch">dsearch(..)</link> afin de traiter efficacement les tableaux de booléens, d'entiers encodés (de tous formats : 8-16-32 bits signés ou non), ou de nombres réels. Le traitement des tableaux de nombres complexes, de polynômes ou de textes est réalisé par un algorithme plus lent et gourmand en mémoire vive. Pour de meilleures performances avec ces types de données, en particulier si <literal>N</literal> ou/et <literal>H</literal> sont de grandes tailles, l'utilisateur peut préalablement augmenter la taille de la pile dévolue aux variables en utilisant <link type="scilab" linkend="scilab.help/stacksize">stacksize(..)</link>. Lorsque le traitement est long, une jauge de progression est affichée.
120         </para>
121     </refsection>
122     <refsection>
123         <title>Exemples</title>
124         <programlisting role="example"><![CDATA[
125 N = [1 8 4 5 2 1];
126 H = [9 7 4 2 1 4];
127
128 [nb, loc] = members(N, H, "last")
129 // Retourne nb  = [1 0 2 0 1 1] : par exemple, 4 apparait 2 fois dans H.
130 // Et       loc = [5 0 6 0 4 5] : la dernière occurence de 4 figure en 6ème position dans H
131
132 [nb, loc] = members(N, H)
133 // Retourne loc = [5 0 3 0 4 5] : la 1ère occurence de 4 figure en 3ème position dans H
134
135 // avec des hypermatrices. Avec N et H déclarées ci-dessus :
136 N = matrix(N, [3 1 2]);
137 H = matrix(H, [3 1 2]);
138 [nb, loc] = members(N, H, "last")
139
140 // Avec des entiers encodés :
141 N = int8(grand(3, 2, "uin", -5, 5));
142 H = int8(grand(4, 4, "uin", -5, 5));
143 [nb, loc] = members(N, H)
144
145 // Avec des polynômes (à coefficients éventuellement complexes) :
146 z = %z;
147 N = [z (1-z)^2 ; -4 %i*z ];
148 H = [2  %i*z -z  3-z  z  z^3 z];
149 [nb, loc] = members(N, H)
150
151 // Avec des matrices de textes :
152 N = [ "Hi" "Hu" "Allo"];
153 H = [ "Hello" "Bonjour" "Allo"
154       "Holà"  "Allo"  "Hallo"
155       "Hi"    "Hé"    "Salud" ];
156 [nb, loc] = members(N, H, "last")
157
158 // Recherche de rangées :
159  H = [
160   3  3  0
161   4  1  0
162   2  0  3
163   0  1  4
164   3  4  3
165   0  4  1
166   3  1  0
167   ];
168  N = [
169   1  2  3
170   0  1  4
171   3  0  3
172   4  1  0
173   2  0  2
174   ];
175  N, H
176  [nb, loc] = members(N, H, "rows")
177  [nb, loc] = members(N, H, "rows","last")
178  [nb, loc] = members(N, H, "rows","shuffle") // [4 1 0], [0 1 4] et [0 4 1] sont associées
179
180 // Recherche de colonnes, en utilisant N et H définies ci-dessus :
181  N = N.', H = H.'
182  [nb, loc] = members(N, H, "cols", "shuffle")
183
184 ]]></programlisting>
185     </refsection>
186     <refsection role="see also">
187         <title>Voir aussi</title>
188         <simplelist type="inline">
189             <member>
190                 <link type="scilab" linkend="scilab.help/dsearch">dsearch</link>
191             </member>
192             <member>
193                 <link type="scilab" linkend="scilab.help/intersect">intersect</link>
194             </member>
195             <member>
196                 <link type="scilab" linkend="scilab.help/find">find</link>
197             </member>
198             <member>
199                 <link type="scilab" linkend="scilab.help/vectorfind">vectorfind</link>
200             </member>
201         </simplelist>
202     </refsection>
203     <refsection>
204         <title>Historique</title>
205         <revhistory>
206             <revision>
207                 <revnumber>5.5.0</revnumber>
208                 <revremark>Introduction de la fonction members()</revremark>
209             </revision>
210         </revhistory>
211     </refsection>
212 </refentry>