[doc] find() page improved
[scilab.git] / scilab / modules / elementary_functions / help / fr_FR / searchandsort / find.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) 2011 - Bernard DUJARDIN
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 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:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="fr" xml:id="find">
20     <refnamediv>
21         <refname>find</refname>
22         <refpurpose>
23             donne la position des éléments %T ou non nuls d'un tableau booléen ou numérique.
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Séquence d'appel</title>
28         <synopsis>
29             ii = find(x)
30             [i1,i2,..] = find(x)
31             .. = find(x, nmax)
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Paramètres</title>
36         <variablelist>
37             <varlistentry>
38                 <term>x</term>
39                 <listitem>
40                     <para>
41                         Vecteur, matrice, ou hypermatrice de booléens ou de nombres.
42                         Tout nombre non nul est équivalent à %T.
43                         Les vecteurs ou matrices creuses sont acceptés.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>nmax</term>
49                 <listitem>
50                     <para>
51                         un entier donnant le nombre maximal d'indices à retourner.
52                         La valeur par défaut est -1 qui signifie "tous".
53                         Cette option peut être utilisée dans un but d'efficacité
54                         en évitant la recherche de tous les indices.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>ii</term>
60                 <listitem>
61                     <para>
62                         vecteur ligne des indices linéarisés des éléments %T ou non nuls,
63                         ou matrice vide [].
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>i1, i2, ..</term>
69                 <listitem>
70                     <para>
71                         vecteurs ligne des indices directionels des élements %T ou non nuls,
72                         or matrices vides [].
73                     </para>
74                 </listitem>
75             </varlistentry>
76         </variablelist>
77     </refsection>
78     <refsection>
79         <title>Description</title>
80         <para>
81             Si <literal>x</literal> est une matrice booléenne,
82         </para>
83         <para>
84             <literal>ii=find(x)</literal> retourne le vecteur des indices
85             <literal>i</literal> pour lesquels <literal>x(i)</literal> est "vrai".
86             Si aucun élément vrai n'est trouvé find retourne une matrice vide.
87         </para>
88         <para>
89             <literal>[i1,i2,..]=find(x)</literal> retourne le vecteur des indices
90             <literal>i1</literal> (pour les lignes) et <literal>i2</literal> (pour les colonnes),..
91             tel que <literal>x(i1(n),i2(n),..)</literal> est "vrai". Si aucun élément vrai n'est
92             trouvé find retourne des matrices vides dans <literal>i1</literal>,
93             <literal>i2</literal>, ...
94         </para>
95         <para>
96             Si <literal>x</literal> est une matrice standard ou une hypermatrice
97             <literal>find(x)</literal> est interprété comme
98             <literal>find(x&lt;&gt;0).</literal>
99         </para>
100         <para>
101             <literal>find([])</literal> retourne <literal>[].</literal>
102         </para>
103     </refsection>
104     <refsection>
105         <title>Exemples</title>
106         <para>
107             Avec un tableau booléen :
108         </para>
109         <programlisting role="example"><![CDATA[
110 A = [%F %T %T %F ; %T %F %F %T]
111 find(A)
112 find(A,2)
113       ]]></programlisting>
114     <screen><![CDATA[
115 --> A = [%F %T %T %F ; %T %F %F %T]
116  A  =
117   F T T F
118   T F F T
119
120 --> find(A)
121  ans  =
122    2.   3.   5.   8.
123
124 --> find(A,2)
125  ans  =
126    2.   3.
127 ]]></screen>
128     <para>
129         Avec un tableau de nombres :
130     </para>
131         <programlisting role="example"><![CDATA[
132 B = [0 -1 0 3 ; 0 -1 -0.4 0]
133 find(B)
134 [i, j] = find(B);
135 [i' j']
136       ]]></programlisting>
137     <screen><![CDATA[
138 --> B = [0 -1 0 3 ; 0 -1 -0.4 0]
139  B  =
140    0.  -1.   0.    3.
141    0.  -1.  -0.4   0.
142
143 --> find(B)
144  ans  =
145    3.   4.   6.   7.
146
147 --> [i, j] = find(B);
148 --> [i' j']
149  ans  =
150    1.   2.
151    2.   2.
152    2.   3.
153    1.   4.
154 ]]></screen>
155     <para>
156         Avec une hypermatrice de nombres :
157     </para>
158         <programlisting role="example"><![CDATA[
159 E = grand(2,5,2,"uin",1,6)
160 find(E < 4)
161       ]]></programlisting>
162     <screen><![CDATA[
163 --> E = grand(2,5,2,"uin",1,6)
164  E  =
165 (:,:,1)
166    1.   6.   5.   5.   4.
167    6.   5.   3.   4.   4.
168 (:,:,2)
169    2.   4.   3.   6.   5.
170    5.   6.   6.   6.   4.
171
172 --> find(E < 4)
173  ans  =
174    1.   6.   11.   15.
175 ]]></screen>
176     <para>
177          Avec une matrice creuse numérique ou booléenne :
178     </para>
179         <programlisting role="example"><![CDATA[
180 C = [0  3  7  0  9  0
181      0  4  0  0  5  0
182      6  0  1  0  3  8
183     ];
184 C = sparse(C);
185 find(C)
186 find(C, 4)
187
188 // Avec une matrice creuse booléenne
189 D = C > 4
190 full(D)
191 find(D)
192       ]]></programlisting>
193     <screen><![CDATA[
194 --> C = sparse(C);
195 --> find(C)
196  ans  =
197     3.    4.    5.    7.    9.    13.    14.    15.    18.
198
199 -->find(C, 4)
200  ans  =
201     3.    4.    5.    7.
202
203 --> // Avec une matrice creuse booléenne
204 --> D = C > 4
205  D  =
206 (  3,  6) sparse boolean matrix
207 (  1,  3)   T
208 (  1,  5)   T
209 (  2,  5)   T
210 (  3,  1)   T
211 (  3,  6)   T
212
213 --> full(D)
214  ans  =
215   F F T F T F
216   F F F F T F
217   T F F F F T
218
219 -->find(D)
220  ans  =
221     3.    7.    13.    14.    18.
222 ]]></screen>
223     <para>
224         Avec le résultat booléen d'une condition individuelle sur du texte :
225     </para>
226         <programlisting role="example"><![CDATA[
227 beers = ["Desperados", "Leffe", "Kronenbourg", "Heineken"];
228 find(beers == "Leffe")
229 find(beers == "1664")
230       ]]></programlisting>
231     <screen><![CDATA[
232 --> find(beers == "Leffe")
233  ans  =
234    2.
235
236 --> find(beers == "1664")
237  ans  =
238     []
239 ]]></screen>
240     <para>
241         Adressage des éléments sélectionnés :
242     </para>
243         <programlisting role="example"><![CDATA[
244 // a) via leurs indices linéarisés :
245 H = [ 0  -2  -8  4  -5  -1
246      -2   2  -9  5   0   1
247     ];
248 L = H;
249 L(find(L<0)) = -10
250
251 // b) Directement via le tableau de leur statut booléen :
252 L = H;
253 L(L<0) = -10
254       ]]></programlisting>
255     <screen><![CDATA[
256 --> // a) via leurs indices linéarisés :
257 --> H = [ 0  -2  -8  4  -5  -1
258   >      -2   2  -9  5   0   1
259   >     ];
260 --> L = H;
261 --> L(find(L<0)) = -10
262  L  =
263    0.   -10.  -10.   4.  -10.  -10.
264   -10.   2.   -10.   5.   0.    1.
265
266 --> // b) Directement via le tableau de leur statut booléen :
267 --> L = H;
268 --> L(L<0) = -10
269  L  =
270    0.   -10.  -10.   4.  -10.  -10.
271   -10.   2.   -10.   5.   0.    1.
272 ]]></screen>
273     </refsection>
274     <refsection role="see also">
275         <title>Voir aussi</title>
276         <simplelist type="inline">
277             <member>
278                 <link linkend="vectorfind">vectorfind</link>
279             </member>
280             <member>
281                 <link linkend="grep">grep</link>
282             </member>
283             <member>
284                 <link linkend="findobj">findobj</link>
285             </member>
286             <member>
287                 <link linkend="boolean">boolean</link>
288             </member>
289         </simplelist>
290     </refsection>
291 </refentry>