<?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) 2020 - 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:ns4="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="union" xml:lang="pt">
    <refnamediv>
        <refname>union</refname>
        <refpurpose>extrai componentes da união de um vetor</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>
            [v, ka, kb] = union(a, b)
            [v, ka, kb] = union(a, b, orient)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>a, b</term>
                <listitem>
                    matrizes de booleanos, números ou texto. Matrizes booleanas ou numéricas
                    esparsas são aceitos. Os tipos de <varname>a</varname> et de
                    <varname>b</varname> podem ser distintos, mas compatíveis para concatenação.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>orient</term>
                <listitem>
                    orientação do processamento :
                    <itemizedlist>
                        <listitem>
                            1 ou "r": a união é realizada nas linhas.
                        </listitem>
                        <listitem>
                            2 or "c": a união é realizada nas colunas.
                        </listitem>
                    </itemizedlist>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>v</term>
                <listitem>
                    vetor linha, ou matriz. O tipo de dados de <varname>v</varname>
                    é o tipo de resultado <literal>[a(:) ; b(:)]</literal>.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ka</term>
                <listitem>
                    vetor linha de inteiros: Índices em <varname>a</varname> de elementos /
                    linhas / colunas de <varname>v</varname> vindos de <varname>a</varname>.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>kb</term>
                <listitem>
                    vetor linha de inteiros: Índices em <varname>b</varname> dos
                    elementos / linhas / colunas restantes de <varname>v</varname>
                    vindos de <varname>b</varname>.
                    <para/>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            <literal>union(a,b)</literal> retorna um vetor linha ordenado que
            retém as entradas únicas de <literal>[a(:);b(:)]</literal>.
        </para>
        <para>
            <literal>union(a,b,"r")</literal> ou
            <literal>union(a,b,1)</literal>retorna a matriz formada pela união das
            linhas únicas de <literal>a</literal> e <literal>b</literal> em ordem
            lexicográfica ascendente. Neste caso, as matrizes <literal>a</literal> e
            <literal>b</literal> devem ter o mesmo número de colunas.
        </para>
        <para>
            <literal>union(a,b,"c")</literal> ou
            <literal>union(a,b,2)</literal>retorna a matriz formada pela união das
            colunas únicas de <literal>a</literal> e <literal>b</literal> em ordem
            lexicográfica ascendente. Neste caso, as matrizes <literal>a</literal> e
            <literal>b</literal> devem ter o mesmo número de colunas.
        </para>
        <para>
            <literal>[v,ka,kb]=union(a,b)</literal> também retorna vetores de
            índices <literal>ka</literal> e <literal>kb</literal> tais que
            <literal>v</literal> é uma combinação ordenada das entradas
            <literal>a(ka)</literal> e <literal>b(kb)</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
A = [6  7  6 ; 5  8  3 ];
B = [1  7  1  0  6 ];

union(A, B)
[u, ka, kb] = union(A, B)
     ]]></programlisting>
     <screen><![CDATA[
--> union(A, B)
 ans  =
   0.   1.   3.   5.   6.   7.   8.

--> [u, ka, kb] = union(A, B)
 u  =
   0.   1.   3.   5.   6.   7.   8.
 ka  =
   6.   2.   1.   3.   4.
 kb  =
   4.   1.
]]></screen>
        <para/>
        <programlisting role="example"><![CDATA[
A = ["a" "b" "a" "c" "c" "b"
     "b" "c" "a" "b" "c" "c" ];
B = ["b" "a" "c" "c" "b" "a"
     "a" "c" "b" "b" "b" "b" ];

[U, ka, kb] = union(A, B, "c")
     ]]></programlisting>
     <screen><![CDATA[
--> [U, ka, kb] = union(A, B, "c")
 U  =
  "a"  "a"  "a"  "b"  "b"  "b"  "c"  "c"
  "a"  "b"  "c"  "a"  "b"  "c"  "b"  "c"

 ka  =
   3.   1.   2.   4.   5.

 kb  =
   2.   1.   5.
]]></screen>
        <para/>
        <programlisting role="example"><![CDATA[
[F, T] = (%f, %t);
A = sparse([T T F T F T ; F F F F T T ; T F F F F T ]); full(A)
B = sparse([F F T T F F ; T T T T T T ; T F T T T F ]); full(B)

[U, ka, kb] = union(A, B, "c");
issparse(U)
full(U), ka, kb
     ]]></programlisting>
     <screen><![CDATA[
--> A = sparse([T T F T F T ; F F F F T T ; T F F F F T ]); full(A)
 ans  =
  T T F T F T
  F F F F T T
  T F F F F T

--> B = sparse([F F T T F F ; T T T T T T ; T F T T T F ]); full(B)
 ans  =
  F F T T F F
  T T T T T T
  T F T T T F

--> [U, ka, kb] = union(A, B, "c");
--> issparse(U)
 ans  =
  T

--> full(U), ka, kb
 ans  =
  F F F T T T
  F T T F F T
  F F T F T T

 ka  =
   3.   5.   2.   1.   6.
 kb  =
   1.
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="brackets">brackets</link>
            </member>
            <member>
                <link linkend="unique">unique</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>Histórico</title>
        <revhistory>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    Extension to boolean matrices.
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1.1</revnumber>
                <revdescription>
                    Extension to sparse boolean, sparse real, and sparse complex matrices.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
