985e59846146ac67fd3085a931000601e6150c76
[scilab.git] / scilab / modules / elementary_functions / help / fr_FR / searchandsort / 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  * 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" 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">
18     <refnamediv>
19         <refname>members</refname>
20         <refpurpose>dénombre (et localise) dans un tableau chaque élément ou ligne ou colonne d'un autre tableau
21         </refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Séquence d'appel</title>
25         <synopsis>
26             [nb [,loc]] = members(N, H)
27             [nb [,loc]] = members(N, H, "last")
28             [nb [,loc]] = members(N, H, "rows"|"cols")
29             [nb [,loc]] = members(N, H, "rows"|"cols", "last")
30             [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle")
31             [nb [,loc]] = members(N, H, "rows"|"cols", "shuffle", "last")
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Paramètres</title>
36         <variablelist>
37             <varlistentry>
38                 <term>N</term>
39                 <listitem>
40                     <para>
41                         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>.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>H</term>
47                 <listitem>
48                     <para>
49                         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.
50                     </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>Options :</term>
55                 <listitem>
56                     <para>Une à 3 options peuvent être indiquées après H, sans ordre particulier :
57                         <variablelist>
58                             <varlistentry>
59                                 <term>"last"</term>
60                                 <listitem>
61                                     <para>
62                                         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>.
63                                     </para>
64                                 </listitem>
65                             </varlistentry>
66                             <varlistentry>
67                                 <term>"rows", "cols"</term>
68                                 <listitem>
69                                     <para>
70                                         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>.
71                                     </para>
72                                 </listitem>
73                             </varlistentry>
74                             <varlistentry>
75                                 <term>"shuffle"</term>
76                                 <listitem>
77                                     <para>
78                                         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.
79                                     </para>
80                                 </listitem>
81                             </varlistentry>
82                         </variablelist>
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>nb</term>
88                 <listitem>
89                     <para>
90                         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.
91                     </para>
92                     <para>
93                         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> ).
94                     </para>
95                 </listitem>
96             </varlistentry>
97             <varlistentry>
98                 <term>loc</term>
99                 <listitem>
100                     <para>
101                         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>.
102                     </para>
103                     <para>
104                         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.
105                     </para>
106                 </listitem>
107             </varlistentry>
108         </variablelist>
109     </refsection>
110     <refsection>
111         <title>Description</title>
112         <para>
113             <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é.
114             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>.
115             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>.
116         </para>
117         <para>
118             Les valeurs spéciales <literal>%inf</literal> et <literal>-%inf</literal> sont admises dans <literal>N</literal> comme dans <literal>H</literal>.
119             <literal>%nan</literal> est toujours admis dans <literal>N</literal>, mais pas dans <literal>H</literal> en mode normal.
120         </para>
121         <para>
122             En mode normal (élément par élément), members(..) utilise la fonction <link linkend="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. Lorsque le traitement est long, une jauge de progression est affichée.
123         </para>
124     </refsection>
125     <refsection>
126         <title>Exemples</title>
127         <programlisting role="example"><![CDATA[
128 N = [1 8 4 5 2 1];
129 H = [9 7 4 2 1 4];
130
131 [nb, loc] = members(N, H, "last")
132 // Retourne nb  = [1 0 2 0 1 1] : par exemple, 4 apparait 2 fois dans H.
133 // Et       loc = [5 0 6 0 4 5] : la dernière occurence de 4 figure en 6ème position dans H
134
135 [nb, loc] = members(N, H)
136 // Retourne loc = [5 0 3 0 4 5] : la 1ère occurence de 4 figure en 3ème position dans H
137
138 // avec des hypermatrices. Avec N et H déclarées ci-dessus :
139 N = matrix(N, [3 1 2]);
140 H = matrix(H, [3 1 2]);
141 [nb, loc] = members(N, H, "last")
142
143 // Avec des entiers encodés :
144 N = int8(grand(3, 2, "uin", -5, 5));
145 H = int8(grand(4, 4, "uin", -5, 5));
146 [nb, loc] = members(N, H)
147
148 // Avec des polynômes (à coefficients éventuellement complexes) :
149 z = %z;
150 N = [z (1-z)^2 ; -4 %i*z ];
151 H = [2  %i*z -z  3-z  z  z^3 z];
152 [nb, loc] = members(N, H)
153
154 // Avec des matrices de textes :
155 N = [ "Hi" "Hu" "Allo"];
156 H = [ "Hello" "Bonjour" "Allo"
157       "Holà"  "Allo"  "Hallo"
158       "Hi"    "Hé"    "Salud" ];
159 [nb, loc] = members(N, H, "last")
160
161 // Recherche de rangées :
162  H = [
163   3  3  0
164   4  1  0
165   2  0  3
166   0  1  4
167   3  4  3
168   0  4  1
169   3  1  0
170   ];
171  N = [
172   1  2  3
173   0  1  4
174   3  0  3
175   4  1  0
176   2  0  2
177   ];
178  N, H
179  [nb, loc] = members(N, H, "rows")
180  [nb, loc] = members(N, H, "rows","last")
181  [nb, loc] = members(N, H, "rows","shuffle") // [4 1 0], [0 1 4] et [0 4 1] sont associées
182
183 // Recherche de colonnes, en utilisant N et H définies ci-dessus :
184  N = N.', H = H.'
185  [nb, loc] = members(N, H, "cols", "shuffle")
186
187 ]]></programlisting>
188     </refsection>
189     <refsection role="see also">
190         <title>Voir aussi</title>
191         <simplelist type="inline">
192             <member>
193                 <link linkend="dsearch">dsearch</link>
194             </member>
195             <member>
196                 <link linkend="intersect">intersect</link>
197             </member>
198             <member>
199                 <link linkend="grep">grep</link>
200             </member>
201             <member>
202                 <link linkend="find">find</link>
203             </member>
204             <member>
205                 <link linkend="vectorfind">vectorfind</link>
206             </member>
207         </simplelist>
208     </refsection>
209     <refsection>
210         <title>Historique</title>
211         <revhistory>
212             <revision>
213                 <revnumber>5.5.0</revnumber>
214                 <revremark>Introduction de la fonction members()</revremark>
215             </revision>
216         </revhistory>
217     </refsection>
218 </refentry>