[doc] find() page improved
[scilab.git] / scilab / modules / elementary_functions / help / ru_RU / 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="ru" xml:id="find">
20     <refnamediv>
21         <refname>find</refname>
22         <refpurpose>даёт индексы элементов с ненулевым значением или значением %T</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Синтаксис</title>
26         <synopsis>
27             ii = find(x)
28             [i1,i2,..] = find(x)
29             .. = find(x, nmax)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Аргументы</title>
34         <variablelist>
35             <varlistentry>
36                 <term>x</term>
37                 <listitem>
38                     <para>
39                         Вектор, матрица или гиперматрица логических значений или чисел.
40                         Все ненулевые числа считаются значениями %T. Принимаются разрежённые 
41                         матрицы.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>nmax</term>
47                 <listitem>
48                     <para>
49                         целое число, указывающее максимальное количество индексов для возврата.
50                         Значение по умолчанию равно <literal>-1</literal>, которое стоит для 
51                         "все". Эта опция может использоваться для эффективности, чтобы исключить 
52                         поиск всех индексов.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>ii</term>
58                 <listitem>
59                     <para>
60                         вектор-строка линеаризованных индексов с ненулевым значением, или 
61                         значением <literal>%T</literal> или пустая матрица <literal>[]</literal>
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>i1, i2, ..</term>
67                 <listitem>
68                     <para>
69                         векторы-строки индексов направления или пустая матрица 
70                         <literal>[]</literal>
71                     </para>
72                 </listitem>
73             </varlistentry>
74         </variablelist>
75     </refsection>
76     <refsection>
77         <title>Описание</title>
78         <para>
79             Если <varname>x</varname> является матрицей логических значений, то
80         </para>
81         <para>
82             <literal>ii=find(x)</literal> возвращает вектор индексов <literal>i</literal>,
83             для которых <literal>x(i)</literal> соответствует "истине". Если не найден ни один 
84             элемент со значением "истина", то возвращается пустая матрица.
85         </para>
86         <para>
87             <literal>[i1,i2,..]=find(x)</literal> возвращает векторы индексов 
88             <literal>i1</literal> (для строк) и <literal>i2</literal> (для столбцов), 
89             <literal>..</literal> такие, что <literal>x(i1(n),i2(n),..)</literal>
90             соответствует "истине". Если не найден ни один элемент со значением 
91             "истина", то возвращаются пустые матрицы в  <literal>i1</literal>,
92             <literal>i2</literal>, ...
93         </para>
94         <para>
95             Если <varname>x</varname> - это стандартная матрица или гиперматрица,
96             то <literal>find(x)</literal> интерпретируется как 
97             <literal>find(x&lt;&gt;0)</literal>
98         </para>
99         <para>
100             <literal>find([])</literal> возвращает <literal>[]</literal>.
101         </para>
102     </refsection>
103     <refsection>
104         <title>Примеры</title>
105         <para>
106             С входными логическими значениями:
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         С входными числами:
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         С входными гиперматрицами чисел:
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          С входной числовой или логической разрежённой матрицей:
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 // С входной логической разрежённой матрицей
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         С результатом логического поэлементного условия на текстах:
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         Адресация выбранных элементов:
241     </para>
242         <programlisting role="example"><![CDATA[
243 // a) Через их линеаризованные индексы:
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) Непосредственно через массив их логического статуса:
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>Смотрите также</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>