<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://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 that are in a set but not in 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</term>
                <listitem>
                    <para>
                        a set of elements 
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>b</term>
                <listitem>
                    <para>elements to remove from <varname>a</varname>.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>orien</term>
                <listitem>
                    oriented processing:
                    <itemizedlist>
                        <listitem>
                            <literal>"r"</literal>: rows of
                            <varname>a</varname> are searched among <varname>b</varname> ones.
                        </listitem>
                        <listitem>
                            <literal>"c"</literal>: columns of
                            <varname>a</varname> are searched among <varname>b</varname> ones.
                        </listitem>
                        <listitem>
                            no orien: elements of <varname>a</varname> are searched among
                            <varname>b</varname> ones.
                        </listitem>
                    </itemizedlist>
                </listitem>
                <para>
                    If the option <literal>orien="r"</literal> is used, <varname>a</varname>
                    and <varname>b</varname> must have the same number of columns.
                    If the <literal>orien="c"</literal> is used, they must have the same
                    number of rows.
                </para>
            </varlistentry>
            <varlistentry>
                <term>v</term>
                <listitem>
                    Array with <varname>a</varname>'s data type and encoding:
                    <itemizedlist>
                        <listitem>
                            sorted vector of <varname>a</varname>'s components that are not in
                            <varname>b</varname>.
                        </listitem>
                        <listitem>
                            <literal>orien="r"</literal>: matrix of rows of <varname>a</varname>
                            that are not in <varname>b</varname>, sorted in lexicographic order.
                        </listitem>
                        <listitem>
                            <literal>orien="c"</literal>: matrix of columns of <varname>a</varname>
                            that are not in <varname>b</varname>, sorted in lexicographic order.
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ka</term>
                <listitem>
                    <para>
                        vector of linear indices of selected  <varname>a</varname>'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 <varname>a</varname> that are <emphasis role="bold">not</emphasis> in <varname>b</varname>.
        </para>
        <para>
            All duplicates (elements or rows or columns) are removed from <varname>a</varname> and
            from <varname>b</varname> before processing.
        </para>
        <para>
            Both <varname>a</varname> and <varname>b</varname> must have the same
            data type (and integer type), but may mix dense and sparse encoding.
            It can be vectors, matrices or hypermatrices of real or complex numbers, encoded integers, booleans, or strings. Sparse-encoded inputs are also accepted.
        </para>
        <para>
            If <varname>a</varname> is an hypermatrix and the <literal>"r"</literal> option is used,
            <varname>a</varname> is replaced with the matrix of all its rows over all its higher
            dimensions, before processing.
            Same thing if <varname>b</varname> is an hypermatrix.
            If the <literal>"c"</literal> option is used, <varname>a</varname> 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
            <varname>a</varname> and the <varname>orien</varname> option. In all cases, if all
            entities of <varname>a</varname> are in <varname>b</varname>,
            <literal>[]</literal> is returned for <varname>v</varname> as for <varname>ka</varname>:
            <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>
            <varname>v</varname> and <varname>ka</varname> become empty
            if <varname>a</varname> is empty (whatever is <varname>b</varname>), or if all
            <varname>a</varname> elements are in <varname>b</varname>.
        </para>
        <para>
            For booleans, <literal>setdiff(…)</literal> is useful mainly with the "r" or "c" options.
        </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>
                    Extension to complex numbers.
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1.1</revnumber>
                <revdescription>
                    Boolean inputs and sparse inputs (boolean or numeric) are now accepted.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
