<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA - Farid BELAHCENE
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018, 2022 - 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="cat" xml:lang="pt">
    <refnamediv>
        <refname>cat</refname>
        <refpurpose>
            empilha matrizes ou arrays vectoriais numa hipermatriz ou hiperarray
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>y = cat(dim, A1, A2,..., An)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>dim</term>
                <listitem>
                    <para>
                        número inteiro > 0 : índice da dimensão ao longo da qual as matrizes de
                        entrada devem ser empilhadas.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A1,A2,..An</term>
                <listitem>
                    <para>
                        escalares, vetores, matrizes, multi-arrays ou cell arrays,
                        de tipos de dados compatíveis. A1,
                        A2, ..., An, devem ter o mesmo tamanho (excluindo o número de
                        dimensão dim). size(A1,i)=size(A2,i)=...=size(An,i) para i
                        diferente de dim e size(A1,dim), size(A2,dim),...,size(An,dim)
                        podem ser diferentes
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>um escalar, vetor, matriz ou multi-array.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            <literal>y=cat(dim,A1,A2,...,An) :</literal> y é o resutado da
            concatenação dos argumentos de entrada A1, A2, ..., An. Se dim= 1, então
            a concatenação é feita de acordo com as linhas; se dim= 2, então a
            concatenação é feita de acordo com as colunas dos argumentos de
            entrada.
        </para>
        <para>
            <literal>cat(1, A1, A2, A3)</literal> is equivalent to <literal>[A1 ; A2 ; A3]</literal>.
            <literal>cat(2, A1, A2, A3)</literal> is equivalent to <literal>[A1 A2 A3]</literal>.
            Brackets are faster and must be preferred in both cases.
        </para>
        <para>
            When input arrays have not all the same data type, automatical conversion rules similar
            to the <literal>[,]</literal> and <literal>[;]</literal> ones are applied, as described
            in the <link linkend="brackets_Types_conversions">[brackets]</link> page.
        </para>
        <para>
            <literal>cat()</literal> is useful mainly for <literal>dim > 2</literal>, to build an
            hypermatrix or hypercell.
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <para>Example #1: Building a vector along dim #3</para>
        <programlisting role="example"><![CDATA[
cat(3, 4, -1, 3)
 ]]></programlisting>
    <screen><![CDATA[
--> cat(3, 4, -1, 3)
 ans  =
(:,:,1)
   4.
(:,:,2)
  -1.
(:,:,3)
   3.
]]></screen>
    <para/>
        <para>Example #2: Building a matrix of text of size(1,3,2):</para>
        <programlisting role="example"><![CDATA[
cat(3, ["a" "aa" "aaa"], ["b" "bb" "bbb"])
 ]]></programlisting>
    <screen><![CDATA[
--> cat(3, ["a" "aa" "aaa"], ["b" "bb" "bbb"])
 ans  =
(:,:,1)
!a  aa  aaa  !
(:,:,2)
!b  bb  bbb  !
]]></screen>
    <para/>
        <para>Example #3: Stacking separate R G B layers of a mini RGB image:</para>
        <programlisting role="example"><![CDATA[
R = uint8(grand(2,4,"uin",0,255))
G = uint8(grand(2,4,"uin",0,255))
B = uint8(grand(2,4,"uin",0,255))
cat(3, R, G, B)
 ]]></programlisting>
    <screen><![CDATA[
--> R = uint8(grand(2,4,"uin",0,255))
 R  =
  142    8   11  234
  191  249  252   51

--> G = uint8(grand(2,4,"uin",0,255))
 G  =
  255  246  104  89
  152   71  112  17

--> B = uint8(grand(2,4,"uin",0,255))
 B  =
  170  182  39  197
  115  108  16   51

--> cat(3, R, G, B)
 ans  =
(:,:,1)
  142    8   11  234
  191  249  252   51
(:,:,2)
  255  246  104  89
  152   71  112  17
(:,:,3)
  170  182  39  197
  115  108  16   51
]]></screen>
    <para/>
        <para>Example #4: Building an hypercell:</para>
        <programlisting role="example"><![CDATA[
A1 = {%T   "abc" ; (1-%z)^2,  %pi}
A2 = {%s^2, gda(); %F, list(-5, "hello")}
cat(3, A1, A2)
 ]]></programlisting>
    <screen><![CDATA[
--> A1 = {%T   "abc" ; (1-%z)^2,  %pi}
 A1  =
  [1x1 boolean   ]  [1x1 string  ]
  [1x1 polynomial]  [1x1 constant]

--> A2 = {%s^2, gda(); %F, list(-5, "hello")}
 A2  =
  [1x1 polynomial]  [1x1 handle]
  [1x1 boolean   ]  [    list  ]

--> cat(3, A1, A2)
 ans  =
(:,:,1)
  [1x1 boolean   ]  [1x1 string  ]
  [1x1 polynomial]  [1x1 constant]

(:,:,2)
  [1x1 polynomial]  [1x1 handle]
  [1x1 boolean   ]  [    list  ]
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="brackets">brackets [..]</link>
            </member>
            <member>
                <link linkend="lstcat">lstcat</link>
            </member>
            <member>
                <link linkend="permute">permute</link>
            </member>
            <member>
                <link linkend="matrix">matrix</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>Histórico</title>
        <revhistory>
            <revision>
                <revnumber>2023.1</revnumber>
                <revdescription>
                    Arrays of compatible types accepted, according to [,] and [;] transtyping rules.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
