* Bugs 15866 & 15867 fixed: setdiff() + 'r'|'c' & integers
[scilab.git] / scilab / modules / elementary_functions / help / ru_RU / setoperations / setdiff.xml
index 2ecb4b3..5adf70a 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2018 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="setdiff" xml:lang="ru">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="setdiff" xml:lang="ru">
     <refnamediv>
         <refname>setdiff</refname>
-        <refpurpose>возвращает элементы вектора, которые не принадлежат другому вектору</refpurpose>
+        <refpurpose>
+            возвращает элементы или строк или столбцов массива, которые не принадлежат другому массиву
+        </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
-        <synopsis>v=setdiff(a,b)
-            [v,ka]=setdiff(a,b)
+        <synopsis>
+            v = setdiff(a, b)
+            v = setdiff(a, b, orien)
+            [v, ka] = setdiff(..)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
         <variablelist>
             <varlistentry>
-                <term>a</term>
+                <term>a, b</term>
                 <listitem>
-                    <para>вектор вещественных чисел или строк</para>
+                    <para>
+                        векторы, матрицы или гиперматрицы вещественных чисел или кодированных 
+                        целых чисел или строк. Оба должны иметь одинаковые типы данных (или типы 
+                        целых чисел).
+                    </para>
+                    <para>
+                        Если используется опция <literal>orien="r"</literal>, то 
+                        <literal>a</literal> и <literal>b</literal> должны иметь одинаковое 
+                        количество столбцов. Если используется <literal>orien="c"</literal>, то 
+                        они должны иметь одинаковое количество строк.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>b</term>
+                <term>orien</term>
                 <listitem>
-                    <para>вектор вещественных чисел или строк</para>
+                    направленная обработка:
+                    <itemizedlist>
+                        <listitem>
+                            <literal>"r"</literal>: строки из <literal>a</literal> ищутся среди строк в <literal>b</literal>.
+                        </listitem>
+                        <listitem>
+                            <literal>"c"</literal>: столбцы из <literal>a</literal> ищутся среди
+                            столбцов в <literal>b</literal>.
+                        </listitem>
+                        <listitem>
+                            <varname>orien</varname> не указано: элементы из <literal>a</literal> 
+                            ищутся среди элементов <literal>b</literal>.
+                        </listitem>
+                    </itemizedlist>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>v</term>
                 <listitem>
-                    <para>
-                        вектор вещественных чисел или строк с той же ориентацией, что и у                 <literal>a</literal>
-                    </para>
+                    <itemizedlist>
+                        <listitem>
+                            сортированный вектор из компонентов <literal>a</literal>, которые 
+                            отсутствуют в <literal>b</literal>.
+                        </listitem>
+                        <listitem>
+                            <literal>orien="r"</literal>: матрица строк из <literal>a</literal>,
+                            которые отсутствуют в <literal>b</literal>, отсортированный в 
+                            лексикографическом порядке.
+                        </listitem>
+                        <listitem>
+                            <literal>orien="c"</literal>: матрица столбцов из 
+                            <literal>a</literal>, которые отсутствуют в <literal>b</literal>, 
+                            отсортированный в лексикографическом порядке.
+                        </listitem>
+                    </itemizedlist>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>ka</term>
                 <listitem>
                     <para>
-                        вектор-строка целых чисел, <literal>ka(i)</literal> - положение
-                        <literal>v(i)</literal> в <literal>a</literal>
+                        вектор линейный индексов выбранных элементов, строк, столбцов из 
+                        <literal>a</literal> таких, что
+                        <itemizedlist>
+                            <listitem>
+                                <literal>v = a(ka)</literal> либо
+                            </listitem>
+                            <listitem>
+                                <literal>v = a(ka,:)</literal> (<literal>orien="r"</literal>) либо
+                            </listitem>
+                            <listitem>
+                                <literal>v = a(:,ka)</literal> (<literal>orien="c"</literal>)
+                            </listitem>
+                        </itemizedlist>
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Описание</title>
         <para>
-            <literal>setdiff(a,b)</literal> возвращает отсортированный вектор, который содержит
-            элементы <literal>a</literal>, которые отсутствуют в <literal>b</literal>.
+            <literal>setdiff(a, b,..)</literal> вычисляет и возвращает элементы либо строк либо 
+            столбцов из <literal>a</literal> которые ОТСУТСТВУЮТ в <literal>b</literal>.
         </para>
         <para>
-            <literal>[v,ka]=setdiff(a,b)</literal> возвращает отсортированный вектор, который
-            содержит элементы <literal>a</literal>, отсутствующие в <literal>b</literal> и
-            положение этих элементов в <literal>a</literal>.
+            Все дупликаты (элементы или строк или столбцов) удаляются из <literal>a</literal> и
+            из <literal>b</literal> перед обработкой.
+        </para>
+        <para>
+            Если <literal>a</literal> - гиперматрица и используется опция <literal>"r"</literal>, 
+            то перед обработкой <literal>a</literal> заменяется матрицей, состоящией из строк по 
+            всем своим более высоким размерностям. То же самое и в случае, если 
+            <literal>b</literal> является гиперматрицей. Если исползуется опция 
+            <literal>"c"</literal>, то <literal>a</literal> или/и <literal>"b"</literal> 
+            заменяются соответствующими матрицами, состоящими из всех своих столбцов.
+        </para>
+        <para>
+            Формат результатов представлен в следующей таблице, в соответствии с формой
+            <literal>a</literal> и опцией <literal>orien</literal>. Во всех случаях, если все элементы <literal>a</literal> находятся в <literal>b</literal>, возвращается
+            <literal>[]</literal> для <literal>v</literal> как для <literal>ka</literal>:
+            <table>
+                <tr>
+                    <th align="right">orien →</th>
+                    <td colspan="2" align="center"><emphasis role="bold">отсутствует</emphasis></td>
+                    <td colspan="2" align="center"><emphasis role="bold">"r"</emphasis></td>
+                    <td colspan="2" align="center"><emphasis role="bold">"c"</emphasis></td>
+                </tr>
+                <tr>
+                    <th>a ↓</th><th>v</th><th>ka</th><th>v</th><th>ka</th><th>v</th><th>ka</th>
+                </tr>
+                <tr>
+                    <td align="right"><emphasis role="bold">строка</emphasis></td>
+                    <td>cтр</td><td>cтр</td>
+                    <td>cтр</td><td>скал</td>
+                    <td>cтр</td><td>cтр</td>
+                </tr>
+                <tr>
+                    <td align="right"><emphasis role="bold">столбец</emphasis></td>
+                    <td>cтлб</td><td>cтлб</td>
+                    <td>cтлб</td><td>cтлб</td>
+                    <td>cтлб</td><td>скал</td>
+                </tr>
+                <tr>
+                    <td align="right"><emphasis role="bold">матрица</emphasis></td>
+                    <td>cтлб</td><td>cтлб</td>
+                    <td>матр</td><td>cтлб</td>
+                    <td>матр</td><td>cтр</td>
+                </tr>
+                <tr>
+                    <td align="right"><emphasis role="bold">гиперматрица</emphasis></td>
+                    <td>cтлб</td><td>cтлб</td>
+                    <td>матр</td><td>cтлб</td>
+                    <td>матр</td><td>cтр</td>
+                </tr>
+                <tr align="center">
+                    <td align="right"><emphasis role="bold">скаляр</emphasis></td>
+                    <td>скал</td><td>скал</td>
+                    <td>скал</td><td>скал</td>
+                    <td>скал</td><td>скал</td>
+                </tr>
+            </table>
+        </para>
+        <para>
+            <literal>v</literal> и <literal>ka</literal> становятся пустыми 
+            <literal>[]</literal>, если <literal>a</literal> пуста (либо <literal>b</literal>), или все элементы <literal>a</literal> находятся в <literal>b</literal>.
         </para>
     </refsection>
     <refsection>
         <title>Примеры</title>
+        <para>
+            <emphasis role="bold">Пример №1:</emphasis>
+        </para>
         <programlisting role="example"><![CDATA[
-a = [223;111;2;4;2;2];
-b = [2;3;21;223;123;22];
-setdiff(a,b)
-[v,k]=setdiff(string(a),string(b))
+a = grand(1, 10,"uin", 0, 9)
+b = grand(2, 4, "uin", 0, 9)
+[d, k] = setdiff(a, b);
+d, k
  ]]></programlisting>
+    <screen><![CDATA[
+--> a = grand(1, 10,"uin", 0, 9)
+ a  =
+   2.   2.   4.   5.   4.   1.   9.   5.   8.   3.
+--> b = grand(2, 4, "uin", 0, 9)
+ b  =
+   5.   0.   9.   9.
+   5.   6.   0.   4.
+--> [d, k] = setdiff(a, b);
+--> d, k
+ d  =
+   1.   2.   3.   8.
+ k  =
+   6.   1.   10.   9.
+ ]]></screen>
+        <para>
+            <emphasis role="bold">Пример №2: постолбцовая обработка</emphasis>
+        </para>
+        <programlisting role="example"><![CDATA[
+a = grand(2, 7,"uin", 0, 3)
+b = grand(2, 10, "uin", 0, 3)
+[d, k] = setdiff(a, b, "c");
+d, k
+ ]]></programlisting>
+    <screen><![CDATA[
+--> a = grand(2, 7,"uin", 0, 3)
+ a  =
+   0.   1.   0.   2.   3.   0.   2.
+   2.   2.   2.   1.   0.   1.   2.
+--> b = grand(2, 10, "uin", 0, 3)
+ b  =
+   1.   1.   3.   1.   1.   1.   3.   0.   2.   0.
+   3.   3.   2.   2.   0.   0.   1.   0.   1.   0.
+--> [d, k] = setdiff(a, b, "c");
+--> d, k
+ d  =
+   0.   0.   2.   3.
+   1.   2.   2.   0.
+ k  =
+   6.   1.   7.   5.
+ ]]></screen>
+        <para>
+            <emphasis role="bold">Пример №3: с текстом</emphasis>
+        </para>
+        <programlisting role="example"><![CDATA[
+v1 = tokens("ab  ca  ba  bb  ca  cb  ba  aa  cc  bc  ac  aa")'
+v2 = tokens("cc  ac  ca  bb  ac  bc  ab")'
+[r, k] = setdiff(v1, v2);
+r, k
+]]></programlisting>
+    <screen><![CDATA[
+--> v1 = tokens("ab  ca  ba  bb  ca  cb  ba  aa  cc  bc  ac  aa")'
+ v1  =
+!ab  ca  ac  bb  ca  cb  ba  aa  cc  bc  ac  aa  !
+--> v2 = tokens("cc  ac  ca  bb  ac  bc  ab")'
+ v2  =
+!cc  ac  ca  bb  ac  bc  ab  !
+--> [r, k] = setdiff(v1, v2);
+--> r, k
+ r  =
+!aa  ba  cb  !
+ k  =
+   8.   3.   6.
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>Смотрите также</title>
@@ -86,11 +264,31 @@ setdiff(a,b)
                 <link linkend="unique">unique</link>
             </member>
             <member>
-                <link linkend="gsort">gsort</link>
+                <link linkend="union">union</link>
             </member>
             <member>
-                <link linkend="union">union</link>
+                <link linkend="members">members</link>
+            </member>
+            <member>
+                <link linkend="vertorfind">vectorfind</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>&lt; 5.0</revnumber>
+                <revdescription>
+                    Функция введена.
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.0.2</revnumber>
+                <revdescription>
+                    Добавлены опции "r" | "c", включая гиперматрицы.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>