[doc] find() page improved
[scilab.git] / scilab / modules / elementary_functions / help / en_US / 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: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="en" xml:id="find">
20     <refnamediv>
21         <refname>find</refname>
22         <refpurpose>gives the indices of %T or non-zero elements</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             ii = find(x)
28             [i1,i2,..] = find(x)
29             .. = find(x, nmax)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>x</term>
37                 <listitem>
38                     <para>
39                         Vector, matrix, or hypermatrix of booleans or of numbers.
40                         All non-zero numbers are considered as %T.
41                         Sparse matrices are accepted.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>nmax</term>
47                 <listitem>
48                     <para>
49                         an integer giving the maximum number of indices to return.
50                         The default value is -1 which stands for "all".
51                         This option can be used for efficiency, to avoid searching all indices.
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>ii</term>
57                 <listitem>
58                     <para>
59                         row vector of linearized indices of %T or non-zero elements, or empty matrix []
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>i1, i2, ..</term>
65                 <listitem>
66                     <para>
67                         row vectors of directional indices, or empty matrix []
68                     </para>
69                 </listitem>
70             </varlistentry>
71         </variablelist>
72     </refsection>
73     <refsection>
74         <title>Description</title>
75         <para>
76             If <literal>x</literal> is a boolean matrix,
77         </para>
78         <para>
79             <literal>ii=find(x)</literal> returns the vector
80             of indices <literal>i</literal> for which <literal>x(i)</literal> is "true". If no true element
81             found find returns an empty matrix.
82         </para>
83         <para>
84             <literal>[i1,i2,..]=find(x)</literal> returns vectors of indices <literal>i1</literal> (for rows) and <literal>i2</literal> (for columns),..
85             such that <literal>x(i1(n),i2(n),..)</literal> is "true". If no true element
86             found find returns  empty matrices in <literal>i1</literal>,
87             <literal>i2</literal>, ...
88         </para>
89         <para>
90             if <literal>x</literal> is a standard matrix or hypermatrix <literal>find(x)</literal> is interpreted as
91             <literal>find(x&lt;&gt;0)</literal>
92         </para>
93         <para>
94             <literal>find([])</literal> returns <literal>[]</literal>
95         </para>
96     </refsection>
97     <refsection>
98         <title>Examples</title>
99         <para>
100             With input booleans:
101         </para>
102         <programlisting role="example"><![CDATA[
103 A = [%F %T %T %F ; %T %F %F %T]
104 find(A)
105 find(A,2)
106       ]]></programlisting>
107     <screen><![CDATA[
108 --> A = [%F %T %T %F ; %T %F %F %T]
109  A  =
110   F T T F
111   T F F T
112
113 --> find(A)
114  ans  =
115    2.   3.   5.   8.
116
117 --> find(A,2)
118  ans  =
119    2.   3.
120 ]]></screen>
121     <para>
122         With input numbers:
123     </para>
124         <programlisting role="example"><![CDATA[
125 B = [0 -1 0 3 ; 0 -1 -0.4 0]
126 find(B)
127 [i, j] = find(B);
128 [i' j']
129       ]]></programlisting>
130     <screen><![CDATA[
131 --> B = [0 -1 0 3 ; 0 -1 -0.4 0]
132  B  =
133    0.  -1.   0.    3.
134    0.  -1.  -0.4   0.
135
136 --> find(B)
137  ans  =
138    3.   4.   6.   7.
139
140 --> [i, j] = find(B);
141 --> [i' j']
142  ans  =
143    1.   2.
144    2.   2.
145    2.   3.
146    1.   4.
147 ]]></screen>
148     <para>
149         With an input hypermatrix of numbers:
150     </para>
151         <programlisting role="example"><![CDATA[
152 E = grand(2,5,2,"uin",1,6)
153 find(E < 4)
154       ]]></programlisting>
155     <screen><![CDATA[
156 --> E = grand(2,5,2,"uin",1,6)
157  E  =
158 (:,:,1)
159    1.   6.   5.   5.   4.
160    6.   5.   3.   4.   4.
161 (:,:,2)
162    2.   4.   3.   6.   5.
163    5.   6.   6.   6.   4.
164
165 --> find(E < 4)
166  ans  =
167    1.   6.   11.   15.
168 ]]></screen>
169     <para>
170          With an input numerical or boolean sparse matrix:
171     </para>
172         <programlisting role="example"><![CDATA[
173 C = [0  3  7  0  9  0
174      0  4  0  0  5  0
175      6  0  1  0  3  8
176     ];
177 C = sparse(C);
178 find(C)
179 find(C, 4)
180
181 // With input boolean sparse
182 D = C > 4
183 full(D)
184 find(D)
185       ]]></programlisting>
186     <screen><![CDATA[
187 --> C = sparse(C);
188 --> find(C)
189  ans  =
190     3.    4.    5.    7.    9.    13.    14.    15.    18.
191
192 -->find(C, 4)
193  ans  =
194     3.    4.    5.    7.
195
196 --> // With input boolean sparse
197 --> D = C > 4
198  D  =
199 (  3,  6) sparse boolean matrix
200 (  1,  3)   T
201 (  1,  5)   T
202 (  2,  5)   T
203 (  3,  1)   T
204 (  3,  6)   T
205
206 --> full(D)
207  ans  =
208   F F T F T F
209   F F F F T F
210   T F F F F T
211
212 -->find(D)
213  ans  =
214     3.    7.    13.    14.    18.
215 ]]></screen>
216     <para>
217         With the result of a boolean element-wise condition on texts:
218     </para>
219         <programlisting role="example"><![CDATA[
220 beers = ["Desperados", "Leffe", "Kronenbourg", "Heineken"];
221 find(beers == "Leffe")
222 find(beers == "1664")
223       ]]></programlisting>
224     <screen><![CDATA[
225 --> find(beers == "Leffe")
226  ans  =
227    2.
228
229 --> find(beers == "1664")
230  ans  =
231     []
232 ]]></screen>
233     <para>
234         Addressing selected elements:
235     </para>
236         <programlisting role="example"><![CDATA[
237 // a) Through their linearized indices:
238 H = [ 0  -2  -8  4  -5  -1
239      -2   2  -9  5   0   1
240     ];
241 L = H;
242 L(find(L < 0)) = -10
243
244 // b) Directly through the array of their boolean status:
245 L = H;
246 L(L < 0) = -10
247       ]]></programlisting>
248     <screen><![CDATA[
249 --> // a) Through their linearized indices:
250 --> H = [ 0  -2  -8  4  -5  -1
251   >      -2   2  -9  5   0   1
252   >     ];
253 --> L = H;
254 --> L(find(L < 0)) = -10
255  L  =
256    0.   -10.  -10.   4.  -10.  -10.
257   -10.   2.   -10.   5.   0.    1.
258
259 --> // b) Directly through the array of their boolean status:
260 --> L = H;
261 --> L(L < 0) = -10
262  L  =
263    0.   -10.  -10.   4.  -10.  -10.
264   -10.   2.   -10.   5.   0.    1.
265 ]]></screen>
266     </refsection>
267     <refsection role="see also">
268         <title>See also</title>
269         <simplelist type="inline">
270             <member>
271                 <link linkend="vectorfind">vectorfind</link>
272             </member>
273             <member>
274                 <link linkend="grep">grep</link>
275             </member>
276             <member>
277                 <link linkend="findobj">findobj</link>
278             </member>
279             <member>
280                 <link linkend="boolean">boolean</link>
281             </member>
282         </simplelist>
283     </refsection>
284 </refentry>