[doc] find() page improved
[scilab.git] / scilab / modules / elementary_functions / help / pt_BR / 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) INRIA
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: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="find" xml:lang="pt">
20     <refnamediv>
21         <refname>find</refname>
22         <refpurpose>
23             fornece os índices de elementos %T ou diferentes de zero
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Seqüência de Chamamento</title>
28         <synopsis>
29             ii = find(x)
30             [i1,i2,..] = find(x)
31             .. = find(x, nmax)
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Parâmetros</title>
36         <variablelist>
37             <varlistentry>
38                 <term>x</term>
39                 <listitem>
40                     <para>
41                         vetor, matriz ou hipermatriz de booleanos ou de números.
42                         Todos os números diferentes de zero são considerados como %T.
43                         Matrizes esparsas são aceitas.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>nmax</term>
49                 <listitem>
50                     <para>um inteiro fornecendo o número máximo de índices a serem
51                         retornados. o valor padrão é -1, que significa "todos". Esta opção
52                         pode ser usada por eficiência, para evitar uma busca por todos os
53                         índices.
54                     </para>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>ii</term>
59                 <listitem>
60                     <para>
61                         vetor de linha de índices linearizados de elementos %T ou diferentes
62                         de zero, ou matriz vazia [].
63                     </para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>i1, i2, ..</term>
68                 <listitem>
69                     <para>
70                         vetores de linha de índices direcionais, ou matriz vazia [].
71                     </para>
72                 </listitem>
73             </varlistentry>
74         </variablelist>
75     </refsection>
76     <refsection>
77         <title>Descrição</title>
78         <para>
79             Se <literal>x</literal> é uma matriz booleana,
80         </para>
81         <para>
82             <literal>ii=find(x)</literal> retorna o vetor de índices
83             <literal>i</literal> para os quais <literal>x(i)</literal> é "true"
84             ("verdadeiro").Se nenhum elemento "true" for encontrado, retorna uma
85             matriz vazia.
86         </para>
87         <para>
88             <literal>[i1,i2,..]=find(x)</literal> retorna vetores de índices
89             <literal>i1</literal> (para linhas) e <literal>i2</literal> (para
90             colunas),... tais que <literal>x(i1(n),i2(n),..)</literal> ié "true"
91             ("verdadeiro"). Se nenhum elemento "true" for encontrado, retorna matrizes
92             vazias em <literal>i1</literal>, <literal>i2</literal>, ...
93         </para>
94         <para>
95             Se <literal>x</literal> é uma matriz ou hipermatriz padrão
96             <literal>find(x)</literal> é interpretado como
97             <literal>find(x&lt;&gt;0)</literal>
98         </para>
99         <para>
100             <literal>find([])</literal> retorna <literal>[]</literal>
101         </para>
102     </refsection>
103     <refsection>
104         <title>Exemplos</title>
105         <para>
106             With input booleans:
107         </para>
108         <programlisting role="example"><![CDATA[
109 A = [%F %T %T %F ; %T %F %F %T]
110 find(A)
111 find(A,2)
112       ]]></programlisting>
113     <screen><![CDATA[
114 --> A = [%F %T %T %F ; %T %F %F %T]
115  A  =
116   F T T F
117   T F F T
118
119 --> find(A)
120  ans  =
121    2.   3.   5.   8.
122
123 --> find(A,2)
124  ans  =
125    2.   3.
126 ]]></screen>
127     <para>
128         With input numbers:
129     </para>
130         <programlisting role="example"><![CDATA[
131 B = [0 -1 0 3 ; 0 -1 -0.4 0]
132 find(B)
133 [i, j] = find(B);
134 [i' j']
135       ]]></programlisting>
136     <screen><![CDATA[
137 --> B = [0 -1 0 3 ; 0 -1 -0.4 0]
138  B  =
139    0.  -1.   0.    3.
140    0.  -1.  -0.4   0.
141
142 --> find(B)
143  ans  =
144    3.   4.   6.   7.
145
146 --> [i, j] = find(B);
147 --> [i' j']
148  ans  =
149    1.   2.
150    2.   2.
151    2.   3.
152    1.   4.
153 ]]></screen>
154     <para>
155         With an input hypermatrix of numbers:
156     </para>
157         <programlisting role="example"><![CDATA[
158 E = grand(2,5,2,"uin",1,6)
159 find(E < 4)
160       ]]></programlisting>
161     <screen><![CDATA[
162 --> E = grand(2,5,2,"uin",1,6)
163  E  =
164 (:,:,1)
165    1.   6.   5.   5.   4.
166    6.   5.   3.   4.   4.
167 (:,:,2)
168    2.   4.   3.   6.   5.
169    5.   6.   6.   6.   4.
170
171 --> find(E < 4)
172  ans  =
173    1.   6.   11.   15.
174 ]]></screen>
175     <para>
176          With an input numerical or boolean sparse matrix:
177     </para>
178         <programlisting role="example"><![CDATA[
179 C = [0  3  7  0  9  0
180      0  4  0  0  5  0
181      6  0  1  0  3  8
182     ];
183 C = sparse(C);
184 find(C)
185 find(C, 4)
186
187 // With input boolean sparse
188 D = C > 4
189 full(D)
190 find(D)
191       ]]></programlisting>
192     <screen><![CDATA[
193 --> C = sparse(C);
194 --> find(C)
195  ans  =
196     3.    4.    5.    7.    9.    13.    14.    15.    18.
197
198 -->find(C, 4)
199  ans  =
200     3.    4.    5.    7.
201
202 --> // With input boolean sparse
203 --> D = C > 4
204  D  =
205 (  3,  6) sparse boolean matrix
206 (  1,  3)   T
207 (  1,  5)   T
208 (  2,  5)   T
209 (  3,  1)   T
210 (  3,  6)   T
211
212 --> full(D)
213  ans  =
214   F F T F T F
215   F F F F T F
216   T F F F F T
217
218 -->find(D)
219  ans  =
220     3.    7.    13.    14.    18.
221 ]]></screen>
222     <para>
223         With the result of a boolean element-wise condition on texts
224     </para>
225         <programlisting role="example"><![CDATA[
226 beers = ["Desperados", "Leffe", "Kronenbourg", "Heineken"];
227 find(beers == "Leffe")
228 find(beers == "1664")
229       ]]></programlisting>
230     <screen><![CDATA[
231 --> find(beers == "Leffe")
232  ans  =
233    2.
234
235 --> find(beers == "1664")
236  ans  =
237     []
238 ]]></screen>
239     <para>
240         Addressing selected elements:
241     </para>
242         <programlisting role="example"><![CDATA[
243 // a) Through their linearized indices:
244 H = [ 0  -2  -8  4  -5  -1
245      -2   2  -9  5   0   1
246     ];
247 L = H;
248 L(find(L < 0)) = -10
249
250 // b) Directly through the array of their boolean status:
251 L = H;
252 L(L < 0) = -10
253       ]]></programlisting>
254     <screen><![CDATA[
255 --> // a) Through their linearized indices:
256 --> H = [ 0  -2  -8  4  -5  -1
257   >      -2   2  -9  5   0   1
258   >     ];
259 --> L = H;
260 --> L(find(L < 0)) = -10
261  L  =
262    0.   -10.  -10.   4.  -10.  -10.
263   -10.   2.   -10.   5.   0.    1.
264
265 --> // b) Directly through the array of their boolean status:
266 --> L = H;
267 --> L(L < 0) = -10
268  L  =
269    0.   -10.  -10.   4.  -10.  -10.
270   -10.   2.   -10.   5.   0.    1.
271 ]]></screen>
272     </refsection>
273     <refsection role="see also">
274         <title>Ver Também</title>
275         <simplelist type="inline">
276             <member>
277                 <link linkend="vectorfind">vectorfind</link>
278             </member>
279             <member>
280                 <link linkend="grep">grep</link>
281             </member>
282             <member>
283                 <link linkend="findobj">findobj</link>
284             </member>
285             <member>
286                 <link linkend="boolean">boolean</link>
287             </member>
288         </simplelist>
289     </refsection>
290 </refentry>