<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA - Farid BELAHCENE
 * 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.
 * 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="cat" xml:lang="en">
    <refnamediv>
        <refname>cat</refname>
        <refpurpose>stacks vectors matrices or arrays into an hypermatrix or hyperarray</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>y = cat(dim, A1, A2, ...,An)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>dim</term>
                <listitem>
                    <para>
                        integer>0: index of the dimension along which input arrays must be stacked.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A1, A2,..An</term>
                <listitem>
                    <para>
                        scalars, vectors, matrices or hypermatrices of the same data type,
                        or cells arrays.
                        <literal>A1,A2,...,An</literal> must be of the same sizes, except in the
                        direction #<literal>dim</literal> of stacking :
                        <literal>size(A1,i)=size(A2,i)=...=size(An,i)</literal> for all
                        <literal>i &lt;> dim</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                        a vector, matrix, hypermatrix of A1's data type, or an hypercell.
                        For all <literal>i &lt;> dim</literal>,
                        <literal>size(y,i)==size(A1,i)</literal>, and
                        <literal>size(y,dim) == sum(size(Ai, dim)))</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>y=cat(dim,A1,A2,...,An)</literal> : <literal>y</literal> is the result of the
            concatenation of the input arguments <literal>A1,A2,...,An</literal>, along the
            dimension #dim.
        </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>
            <literal>cat()</literal> is useful mainly for <literal>dim > 2</literal>, to build an
            hypermatrix or hypercell.
        </para>
    </refsection>
    <refsection>
        <title>Examples</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>See also</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>
</refentry>
