<?xml version="1.0" encoding="UTF-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 - 2019 - 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.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * 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="en">
    <refnamediv>
        <refname>setdiff</refname>
        <refpurpose>
            returns elements or rows or columns of an array that do not belong to another one
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            v = setdiff(a, b)
            v = setdiff(a, b, orien)
            [v, ka] = setdiff(..)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>a, b</term>
                <listitem>
                    <para>
                        vectors, matrices or hypermatrices of real or complex numbers, or encoded
                        integers, or strings. Both must have the same data types (and integer types).
                    </para>
                    <para>
                        If the option <literal>orien="r"</literal> is used, <literal>a</literal>
                        and <literal>b</literal> must have the same number of columns.
                        If the <literal>orien="c"</literal> is used, they must have the same
                        number of rows.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>orien</term>
                <listitem>
                    oriented processing:
                    <itemizedlist>
                        <listitem>
                            <literal>"r"</literal>: rows of
                            <literal>a</literal> are searched among <literal>b</literal> ones.
                        </listitem>
                        <listitem>
                            <literal>"c"</literal>: columns of
                            <literal>a</literal> are searched among <literal>b</literal> ones.
                        </listitem>
                        <listitem>
                            no orien: elements of <literal>a</literal> are searched among
                            <literal>b</literal> ones.
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>v</term>
                <listitem>
                    <itemizedlist>
                        <listitem>
                            sorted vector of <literal>a</literal>'s components that are not in
                            <literal>b</literal>.
                        </listitem>
                        <listitem>
                            <literal>orien="r"</literal>: matrix of rows of <literal>a</literal>
                            that are not in <literal>b</literal>, sorted in lexicographic order.
                        </listitem>
                        <listitem>
                            <literal>orien="c"</literal>: matrix of columns of <literal>a</literal>
                            that are not in <literal>b</literal>, sorted in lexicographic order.
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ka</term>
                <listitem>
                    <para>
                        vector of linear indices of selected  <literal>a</literal>'s components,
                        rows, or columns, such that
                        <itemizedlist>
                            <listitem>
                                <literal>v = a(ka)</literal>, or
                            </listitem>
                            <listitem>
                                <literal>v = a(ka,:)</literal> (<literal>orien="r"</literal>), or
                            </listitem>
                            <listitem>
                                <literal>v = a(:,ka)</literal> (<literal>orien="c"</literal>)
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>setdiff(a, b,..)</literal> computes and returns the elements or rows or columns
            of <literal>a</literal> that are NOT in <literal>b</literal>.
        </para>
        <para>
            All duplicates (elements or rows or columns) are removed from <literal>a</literal> and
            from <literal>b</literal> before processing.
        </para>
        <para>
            If <literal>a</literal> is an hypermatrix and the <literal>"r"</literal> option is used,
            <literal>a</literal> is replaced with the matrix of all its rows over all its higher
            dimensions, before processing.
            Same thing if <literal>b</literal> is an hypermatrix.
            If the <literal>"c"</literal> option is used, <literal>a</literal> or/and
            <literal>"b"</literal> are replaced with the respective matrices of all their columns.
        </para>
        <para>
            The format of results is presented in the following table, according to the shape of
            <literal>a</literal> and the <literal>orien</literal> option. In all cases, if all
            entities of <literal>a</literal> are in <literal>b</literal>,
            <literal>[]</literal> is returned for <literal>v</literal> as for <literal>ka</literal>:
            <table>
                <tr>
                    <th align="right">orien →</th>
                    <td colspan="2" align="center">
                        <emphasis role="bold">none</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">row</emphasis>
                    </td>
                    <td>row</td><td>row</td>
                    <td>row</td><td>scal</td>
                    <td>row</td><td>row</td>
                </tr>
                <tr>
                    <td align="right">
                        <emphasis role="bold">column</emphasis>
                    </td>
                    <td>col</td><td>col</td>
                    <td>col</td><td>col</td>
                    <td>col</td><td>scal</td>
                </tr>
                <tr>
                    <td align="right">
                        <emphasis role="bold">matrix</emphasis>
                    </td>
                    <td>col</td><td>col</td>
                    <td>mat</td><td>col</td>
                    <td>mat</td><td>row</td>
                </tr>
                <tr>
                    <td align="right">
                        <emphasis role="bold">hypermatrix</emphasis>
                    </td>
                    <td>col</td><td>col</td>
                    <td>mat</td><td>col</td>
                    <td>mat</td><td>row</td>
                </tr>
                <tr align="center">
                    <td align="right">
                        <emphasis role="bold">scalar</emphasis>
                    </td>
                    <td>scal</td><td>scal</td>
                    <td>scal</td><td>scal</td>
                    <td>scal</td><td>scal</td>
                </tr>
            </table>
        </para>
        <para>
            <literal>v</literal> and <literal>ka</literal> become empty <literal>[]</literal>
            if <literal>a</literal> is empty (whatever is <literal>b</literal>), or if all
            <literal>a</literal> elements are in <literal>b</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            <emphasis role="bold">Example #1:</emphasis>
        </para>
        <programlisting role="example"><![CDATA[
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">Example #2: column-wise processing</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">Example #3: with some text</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>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="unique">unique</link>
            </member>
            <member>
                <link linkend="union">union</link>
            </member>
            <member>
                <link linkend="members">members</link>
            </member>
            <member>
                <link linkend="vectorfind">vectorfind</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>&lt; 5.0</revnumber>
                <revdescription>
                    Function introduced.
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.0.2</revnumber>
                <revdescription>
                    Option "r" | "c" added, including for hypermatrices.
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    Complex numbers are now accepted.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
