vectorfind() upgrade: short needle, wildcard, hypermats, %nan
[scilab.git] / scilab / modules / elementary_functions / help / ru_RU / searchandsort / vectorfind.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) 2008 - INRIA - Serge STEER
5  * Copyright (C) 2008 - INRIA - Ramine NIKOUKHAH
6  * Copyright (C) 2010 - DIGITEO - Vincent COUVERT
7  * Copyright (C) 2017 - Samuel GOUGEON
8  *
9  * Copyright (C) 2012 - 2016 - Scilab Enterprises
10  *
11  * This file is hereby licensed under the terms of the GNU GPL v2.0,
12  * pursuant to article 5.3.4 of the CeCILL v.2.1.
13  * This file was originally licensed under the terms of the CeCILL v2.1,
14  * and continues to be available under such terms.
15  * For more information, see the COPYING file which you should have received
16  * along with this program.
17  *
18  -->
19 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
20         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
21         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
22         xmlns:scilab="http://www.scilab.org" xml:id="vectorfind" xml:lang="ru">
23     <refnamediv>
24         <refname>vectorfind</refname>
25         <refpurpose>ищет расположение вектора (отмеченный символом групповой подстановки) в матрице или гиперматрице</refpurpose>
26     </refnamediv>
27     <refsynopsisdiv>
28         <title>Синтаксис</title>
29         <synopsis>
30             ind             = vectorfind(haystack, needle)
31             ind             = vectorfind(haystack, needle, dimAlong)
32             ind             = vectorfind(haystack, needle, dimAlong, ,indType)
33             [ind, matching] = vectorfind(haystack, needle, dimAlong, joker)
34             [ind, matching] = vectorfind(haystack, needle, dimAlong, joker, indType)
35         </synopsis>
36     </refsynopsisdiv>
37     <refsection>
38         <title>Аргументы</title>
39         <variablelist>
40             <varlistentry>
41                 <term>haystack</term>
42                 <listitem>
43                     <para>
44                     Матрица или гиперматрица любого типа, возможно разрежённая: массив в
45             котором будет идти поиск вектора.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>needle</term>
51                 <listitem>
52                     <para>
53                     Вектор, который надо искать в <varname>haystack</varname>, того же самого типа.
54             Если <varname>haystack</varname> является разрежённой, то <varname>needle</varname>
55             может быть неразрежённой. К тому же, если <varname>haystack</varname> является
56             логической и используется <varname>joker</varname>, то <varname>needle</varname>
57             должна быть числовой, а не логической. В этом случае любой её ненулевой элемент
58             считается равным <literal>%T</literal>.
59                     </para>
60                     <note>
61                         <itemizedlist>
62                             <listitem>
63                                 Десятичные числа, комплексные числа и кодированные целые числа считаются
64                 одним типом: числовым.
65                             </listitem>
66                             <listitem>
67                                 Значения <literal>%nan</literal> принимаются в <varname>needle</varname>.
68                 Они обрабатываются обычным способом, как и другие значения. Они совпадают
69                 только с <literal>%nan</literal> в <varname>haystack</varname>.
70                             </listitem>
71                         </itemizedlist>
72                     </note>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>dimAlong</term>
77                 <listitem>
78                     <para>
79               Направление внутри массива <varname>haystack</varname> вдоль которого идёт поиск
80               вектора <varname>needle</varname>. Возможными значениями являются <literal>"r"</literal>
81               или <literal>1</literal> (вдоль строк), <literal>"c"</literal> или <literal>2</literal>
82               (вдоль столбцов) или для гиперматрицы любое целое значение, такое, что
83               <literal>2 &lt; dimAlong &lt;= ndims(haystack)</literal>, представляющее индекс сканируемого измерения. По умолчанию используется <literal>"r"</literal>.
84                     </para>
85                     <important>
86                         <varname>dimAlong</varname> обязателен, когда определён <varname>joker</varname>
87                         или <varname>indType</varname>.
88                     </important>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>joker</term>
93                 <listitem>
94                     <para>
95               Одиночный элемент типа данных <varname>needle</varname>. Элементы <varname>needle</varname>,
96               равные значению <varname>joker</varname> игнорируются (сопоставляются/принимаются любые
97               значения из <varname>haystack</varname>).
98                     </para>
99                     <para>
100               Когда <varname>haystack</varname> является логическим, то <varname>joker</varname>
101               должно быть ненулевым числом.
102                     </para>
103                     <para>
104               Чтобы пропустить <varname>joker</varname>, укажите
105               <literal>..dimAlong, ,indType</literal> без значения <varname>joker</varname>.
106                     </para>
107                 </listitem>
108             </varlistentry>
109             <varlistentry>
110                 <term>indType</term>
111                 <listitem>
112                     <para>
113               Одиночное нечувствительное к регистру слово внутри кавычек <literal>""</literal>
114               (по умолчанию без текста), <literal>"headIJK"</literal> и <literal>"headN"</literal>:
115               Определяет формат или индексы. Смотрите ниже описание переменной <varname>ind</varname>.
116                     </para>
117                 </listitem>
118             </varlistentry>
119             <varlistentry>
120                 <term>ind</term>
121                 <listitem>
122                     <para>
123                     <itemizedlist>
124                         <listitem>
125                             <para>
126                   Если <varname>needle</varname> по размеру больше, чем <varname>haystack</varname>,
127                   в выбранной размерности <varname>dimAlong</varname>, и возвращается
128                   <varname>ind=[]</varname>.
129                             </para>
130                         </listitem>
131                         <listitem>
132                             <para>
133                   Если длина <varname>needle</varname> соответствует по размеру <varname>haystack</varname>
134                   по выбранной размерности:
135                             <itemizedlist>
136                                 <listitem>
137                                     <para>
138                                     <emphasis role="bold">По умолчанию</emphasis>
139                                     (<varname>indType==""</varname>):
140                                     <varname>ind</varname> является вектором-строкой, содержащей индексы совпавших
141                     строк и столбцов <varname>haystack</varname>. В случае гиперматрицы возвращаемые
142                     индексы совпавших диапазонов линеаризованы через все размерности кроме одной
143                     <varname>dimAlong</varname> (см. примеры).
144                                     </para>
145                                 </listitem>
146                                 <listitem>
147                                     <para>
148                                     <emphasis role="bold">indType="headN"</emphasis>:
149                                     <varname>ind</varname> является  вектором-строкой <emphasis role="italic">линейных</emphasis>
150                     индексов в <varname>haystack</varname> первых элементов совпавших строк, столбцов и более высоких диапазонов.
151                                     </para>
152                                 </listitem>
153                                 <listitem>
154                                     <para>
155                                     <emphasis role="bold">indType="headIJK"</emphasis>:
156                                     <varname>ind</varname> является матрицей: каждая строка возвращает
157                                     индексы <literal>[i j ..]</literal> в <varname>haystack</varname> первых
158                     элементов совпавших диапазонов (строки, столбцы или более высокие диапазоны).
159                                     <varname>ind</varname> имеет столько строк, сколько совпавших диапазонов в
160                     <varname>haystack</varname>.
161                                     </para>
162                                 </listitem>
163                             </itemizedlist>
164                             </para>
165                         </listitem>
166                         <listitem>
167                             <para>
168                             В противном случае (короткая <varname>needle</varname>): По умолчанию,
169                             <varname>ind</varname> является  вектором-строкой линейных индексов элементов
170                 <varname>haystack</varname>, где начинаются совпавшие диапазоны. Используя опцию
171                 <literal>indType="headN"</literal> ни к чему не приводит. Использование
172                 <literal>indType="headIJK"</literal> возвращает <varname>ind</varname> в виде матрицы
173                 индексов <literal>[i j k ..]</literal>, как было описано выше.
174                             </para>
175                         </listitem>
176                     </itemizedlist>
177                     </para>
178                     <note>Возвращаемые индексы сортированы в порядке возрастания.</note>
179                 </listitem>
180             </varlistentry>
181             <varlistentry>
182                 <term>matching</term>
183                 <listitem>
184                     <para>
185               Когда используется <varname>matching</varname> выходная необязательная переменная
186               <varname>matching</varname> является матрицей с типом данных, как у
187               <varname>haystack</varname>, возвращающей фактические диапазоны совпадения: диапазон
188               совпадения №i возвращается в строке <literal>matching(i,:)</literal>.
189                     </para>
190                     <note>
191                         Когда <varname>haystack</varname> является разрежённой, то матрица
192             <varname>matching</varname> тоже является разрежённой.
193                     </note>
194                 </listitem>
195             </varlistentry>
196         </variablelist>
197     </refsection>
198     <refsection>
199         <title>Описание</title>
200         <para>
201             <literal>vectorfind()</literal> ищет указанную последовательность значений
202         <varname>needle</varname> (иголка) в массиве <varname>haystack</varname> (стог сена) по указанному
203         прямому направлению/измерению: ширина (строки), высота (столбцы), толщина (подобно пикселям RGB) и т.д.
204         Иголка <varname>needle</varname> может быть длиннее или короче, чем размер исследуемой стороны стога
205         сена <varname>haystack</varname>.
206         </para>
207         <para>
208         Может быть определено специальное значение, так называемый <emphasis role="italic">джокер</emphasis>.
209         Тогда это значение работает, как символ универсальной подстановки там, где он встречается в векторе иглы
210         <varname>needle</varname>. Поскольку это значение более нельзя выбирать, то -- ЛЮБОЕ значение после
211         совпадений в стогу сена <varname>haystack</varname> на своей позиции --, оно не может одновременно
212         использоваться в игле <varname>needle</varname> в качестве выбираемого. На практике любое значение,
213         не представленное в стоге сена <varname>haystack</varname>, обязательно требует хорошего джокера. Однако,
214         это условие не является обязательным.
215         </para>
216         <para>
217             Следовательно: когда стог сена <varname>haystack</varname> является логическим, то джокер -- а также
218         вектор иглы <varname>needle</varname> -- должен быть числовым. Действительно, в противном случае было
219         бы невозможно выбрать значение джокера из ограниченного множества значений <literal>{%T, %F}</literal>.
220         </para>
221         <para>
222         Когда такой символ универсальной подстановки используется, то фактические значения в совпавших
223         диапазонах не фиксируются. Тогда можно получить их благодаря необязательной выходной переменной
224         <varname>matching</varname>. В противном случае <varname>matching</varname> будет пустой (это
225         тривиальный повтор вектора иглы <varname>needle</varname>).
226         </para>
227         <refsect3>
228             <title>Поиск в гиперматрицах</title>
229             <para>
230           Использование <literal>vectorfind()</literal> с гиперматрицей в качестве <varname>haystack</varname>
231           заслуживает несколько особого внимания:
232             <itemizedlist>
233                 <listitem>
234                     <para>О значении направления <literal>dimAlong</literal>:
235                     </para>
236                     <para>
237                         Например, мы можем затем исследовать массив <varname>haystack</varname> по "толщине",
238             то есть  <emphasis role="italic">сквозь</emphasis> её следующие друг за другом слои
239             <literal>haystack(:,:,#,..)</literal>. Чтобы так сделать, мы определим здесь
240             <literal>dimAlong = 3</literal>.
241                     </para>
242                     <para>
243               Как и для матриц, этот вид многомерного массива может быть просканирован
244               <emphasis role="italic">вдоль</emphasis> его строк или столбцов. Подходящие значения
245               <literal>dimAlong</literal> имеют некоторые исключения:
246                     <itemizedlist>
247                         <listitem>
248                 Поиск иглы <emphasis role="italic">как строки</emphasis> сканирует массив
249                 <emphasis role="italic">сквозь его столбцы</emphasis>. Следовательно,
250                 значение <literal>dimAlong = "r"</literal> должно быть эквивалентно значению
251                 <literal>dimAlong = 2</literal> вместо 1!
252                         </listitem>
253                         <listitem>
254                             Аналогично поиск иглы <emphasis role="italic">как столбцы</emphasis> сканирует массив
255                 <emphasis role="italic">сквозь его строки</emphasis>: Обычное значение
256                             <literal>dimAlong = "c"</literal> должно быть эквивалентно значению
257                             <literal>dimAlong = 1</literal> вместо 2!
258                         </listitem>
259                     </itemizedlist>
260                     </para>
261                     <para>
262               Для того, чтобы не нарушать общую договорённость, о том что  <literal>"r"&lt;=>1</literal> и
263               <literal>"c"&lt;=>2</literal> используется везде в Scilab, <literal>vectorfind()</literal>
264               придерживается и справляется с ним. Но нужно иметь в виду лежащий в основе переключатель, чтобы
265               иметь чёткое понимание возвращаемых по умолчанию индексов, когда используются <literal>"r",1</literal>
266               или <literal>"c",2</literal>.
267                     </para>
268                 </listitem>
269                 <listitem>
270                     <para>
271               О возвращаемых индексах совпадающих строк, столбцов, "пикселей"... когда игла <varname>needle</varname>
272               такой же длины, как размер стороны стога сена <varname>haystack</varname> и опция
273               <literal>indType</literal> не используется:
274                     </para>
275                     <para>
276               Индексы совпадающих диапазонов являются <emphasis role="italic">линейными</emphasis>
277               индексами компонентов следующих подпространств:
278                     <itemizedlist>
279                         <listitem>
280                             С <literal>dimAlong = "r" = 1</literal>:
281                             в <literal>haystack(:,1,:,:..)</literal>
282                         </listitem>
283                         <listitem>
284                             С <literal>dimAlong = "c" = 2</literal>:
285                             в <literal>haystack(1,:,:,:..)</literal>
286                         </listitem>
287                         <listitem>
288                             С <literal>dimAlong = 3</literal>:
289                             в <literal>haystack(:,:,1,:..)</literal>
290                         </listitem>
291                         <listitem>
292                             С <literal>dimAlong = 4</literal>:
293                             в <literal>haystack(:,:,:,1,:..)</literal>.
294                         </listitem>
295                         <listitem>
296                             и др...
297                         </listitem>
298                     </itemizedlist>
299                     Случай трёх- и четырёхмерных массивов рассмотрен в разделе примеров.
300                     </para>
301             Несмотря на то, что легко понять и использовать для простых матриц, несколько трудно
302             работать с этими линейными индексами в подпространстве <literal>haystack</literal>,
303             чтобы фактически обращаться к совпадающим диапазонам в ND-мерном массиве с N>2.
304                     Необязательный параметр <literal>indType = "headN" | "headIJK</literal> затем вернёт
305             более удобные в работе индексы, обращающиеся ко всему массиву <literal>haystack</literal>.
306                 </listitem>
307             </itemizedlist>
308             </para>
309         </refsect3>
310     </refsection>
311     <refsection>
312         <title>Примеры</title>
313         <para>
314             <emphasis role="bold">В матрице чисел:</emphasis>
315         </para>
316         <programlisting role="example"><![CDATA[
317 m = [ 1  0   1   2  2  1
318       2  2   0   1  0  2
319       0  2  %nan 2  1  2
320       2 %nan 1   0  1  2
321     ];
322 vectorfind(m,[2 0 1 1], "c")            // => 5
323 vectorfind(m,[2 0 1 1], "c",,"headN")   // => 17
324 vectorfind(m,[2 0 1 1], "c",,"headIJK") // [1 5]
325 // С короткой иглой:
326 vectorfind(m,[2 2])                     // => [2 13]
327 vectorfind(m,[2 2], "r",,"headN")       // тот же выходной параметр
328 vectorfind(m,[2 2], "r",,"headIJK")     // => [2 1 ; 1 4]
329 vectorfind(m,[2 %nan])                  // => [4 7]
330 // С символом универсальной подстановки в игле:
331 // пример №1: все столбцы начинаются с 1 и заканчиваются 2:
332 [n, ma] = vectorfind(m,[1 .3 .3 2], "c", .3) // => n = [1 6], ma = [1 2 0 2; 1 2 2 2]
333 // пример №2: все строки, имеющие диапазон [2 * 2] (короткая игла с символом универсальной подстановки):
334 [n, ma] = vectorfind(m,[2 .3  2], "r", .3)   // => n = [7 15], ma = [2 %nan 2; 2 1 2]
335 vectorfind(m,[2 .3  2], "r", .3, "headIJK")  // => [3 2 ; 3 4]
336                                              // Примечание: значение %nan соответствует *
337  ]]></programlisting>
338         <para>
339             <emphasis role="bold">Логическая матрица:</emphasis>
340         </para>
341         <programlisting role="example"><![CDATA[
342 m = [0  0  0  1  1  0
343      0  1  1  1  0  1
344      1  1  0  1  1  1
345      1  0  1  0  0  1]==1
346 // m  =
347 //  F F F T T F
348 //  F T T T F T
349 //  T T F T T T
350 //  T F T F F T
351 vectorfind(m, [%F %T %T %F], "c")   // => 2
352 vectorfind(m, [%T %T], "c")         // => [3 6 13 14 22 23]
353 vectorfind(m, [1 1], "c")           // => ошибка: ожидался тот же тип
354 // джокер => игла является числовой:
355 [n, ma] = vectorfind(m, [0 %nan 0 %nan 1], "r", %nan) // => n=[1 8], ma=[F F F T T ; F T F F T]
356  ]]></programlisting>
357         <para>
358             <emphasis role="bold">В маленьком 8-цветном RGB-изображении (трёхмерная гиперматрица
359           целых чисел типа uint8):</emphasis>
360         </para>
361         <programlisting role="example"><![CDATA[
362 // Формирование массива яркости цвета:
363 m = [1  1  1  1  1  0  1  0  0  0  1  0  1  0  0
364      1  1  0  0  0  0  1  0  1  0  1  1  1  1  1
365      1  1  0  1  0  1  1  0  0  1  1  0  0  1  0];
366 m = uint8(matrix(m,3,5,3)*255)
367 // m  =
368 //(:,:,1)                   // Красный слой
369 //  255  255  255  255  255
370 //  255  255    0    0    0
371 //  255  255    0  255    0
372 //(:,:,2)                   // Зелёный слой
373 //    0  255    0    0    0
374 //    0  255    0  255    0
375 //  255  255    0    0  255
376 //(:,:,3)                   // Синий слой
377 //  255    0  255    0    0
378 //  255  255  255  255  255
379 //  255    0    0  255    0
380 // Определяет позицию красных пикселей:
381 vectorfind(m, [255 0 0], 3)             // => [10 13]
382 vectorfind(m, [255 0 0], 3,,"headIJK")  // => [1 4 1 ; 1 5 1]
383 // Пиксели с включённым зелёным и синим цветом, каким бы ни был их красный канал:
384 //   Мы можем использовать десятично-кодированную иглу (не uint8).
385 //   Тогда, %nan можно использовать в качестве джокера, который не может быт в изображении с типом uint8:
386 vectorfind(m, [%nan 255 255], 3, %nan,"headIJK") // => [3 1 1; 2 2 1; 2 4 1]
387 // Столбцы из 255:
388 vectorfind(m, [255 255 255], "c")      // => [1 2 7 11]
389  ]]></programlisting>
390         <para>
391             <emphasis role="bold">В четырёхмерной текстовой гиперматрице:</emphasis>
392         </para>
393         <programlisting role="example"><![CDATA[
394 m  = [
395   "U"  "C"  "G"  "A"  "A"  "A"  "U"  "U"  "A"  "G"  "A"  "G"
396   "A"  "A"  "A"  "A"  "C"  "C"  "U"  "U"  "C"  "G"  "G"  "G"
397   "A"  "G"  "A"  "C"  "G"  "C"  "C"  "C"  "G"  "C"  "A"  "G"
398   "C"  "U"  "G"  "G"  "G"  "A"  "A"  "G"  "C"  "C"  "C"  "C"
399   "C"  "G"  "G"  "A"  "A"  "G"  "U"  "C"  "A"  "U"  "G"  "C"
400   ];
401 m = matrix(m, 3, 5, 2, 2);
402 // (:,:,1,1)
403 // !U  C  A  G  A  !
404 // !A  C  G  G  G  !
405 // !A  C  U  A  G  !
406 //(:,:,2,1)
407 // !A  G  C  A  C  !
408 // !A  A  G  A  A  !
409 // !C  A  G  C  G  !
410 //(:,:,1,2)
411 // !U  A  U  C  G  !
412 // !U  U  C  A  C  !
413 // !C  U  G  C  A  !
414 //(:,:,2,2)
415 // !G  C  G  G  G  !
416 // !G  U  A  G  C  !
417 // !C  A  C  G  C  !
418 vectorfind(m, ["A" "A" "C"], "c")       // => [6 9]
419 vectorfind(m, [""  "G" "G"], "c", "")   // => [5 8 19]
420 // Джокер
421 [n, ma] = vectorfind(m, ["" "G" "G"], "c", "", "headN") // => n=[13 22 55], ma=[A G G; C G G; G G G]
422 vectorfind(m, ["" "C" "C"], "c", "", "headIJK") // => [1 2 1 1 ; 1 5 2 2]
423 // Короткая игла
424 vectorfind(m, ["C" "C"], "c",,"headIJK")        // => [1 2 1 1; 2 2 1 1; 2 5 2 2]
425 // Короткая игла с джокером
426 vectorfind(m, ["A" "" "A"],"r","","headIJK")    // => [1 3 1 1 ; 2 2 2 1]
427 ]]></programlisting>
428     </refsection>
429     <refsection role="see also">
430         <title>Смотрите также</title>
431         <simplelist type="inline">
432             <member>
433                 <link linkend="find">find</link>
434             </member>
435             <member>
436                 <link linkend="members">members</link>
437             </member>
438             <member>
439                 <link linkend="grep">grep</link>
440             </member>
441         </simplelist>
442     </refsection>
443     <refsection role="history">
444         <title>История</title>
445         <revhistory>
446             <revision>
447                 <revnumber>6.1</revnumber>
448                 <revdescription>
449                     <itemizedlist>
450                         <listitem>
451                             <literal>vectorfind(H,[])</literal> теперь возвращает <literal>[]</literal>
452                             вместо ошибки.
453                         </listitem>
454                         <listitem>
455                             Когда игла слишком длинная, теперь вместо ошибки возвращается <literal>[]</literal>.
456                         </listitem>
457                         <listitem>
458                             Теперь может быть использована игла, короче, чем размер стога сена.
459                         </listitem>
460                         <listitem>
461                 Значение символа универсальной подстановки, совпавшее с любым значением стога сена теперь может быть
462                 определён и использован в качестве иглы. Затем могут быть возвращены фактически совпадающие диапазоны:
463                 добавлены необязательные параметры <literal>joker</literal> и <literal>matching</literal>.
464                         </listitem>
465                         <listitem>
466                             Любое значение <literal>%nan</literal>, встреченное в игле, теперь обрабатывается
467                 как любое иное регулярное значение: оно соответствует значению <literal>%nan</literal>
468                 в стоге сена. Оно ранее никогда не соответствовало.
469                         </listitem>
470                         <listitem>
471                             Гиперматрицы могут теперь обрабатываться в качестве стога сена.
472                         </listitem>
473                         <listitem>
474                             Исследуемое направление <literal>dimAlong</literal> теперь может быть числовым:
475                             1, 2, ..
476                         </listitem>
477                         <listitem>
478                             Добавлен необязательный параметр <literal>indType</literal>.
479                         </listitem>
480                     </itemizedlist>
481                 </revdescription>
482             </revision>
483         </revhistory>
484     </refsection>
485 </refentry>