[doc] cat() page improved 40/20640/4
Samuel GOUGEON [Mon, 26 Nov 2018 03:58:58 +0000 (04:58 +0100)]
Change-Id: I4518c23803e740bf45c872f0c57da9025adb306b

scilab/modules/elementary_functions/help/en_US/matrixmanipulation/cat.xml
scilab/modules/elementary_functions/help/ja_JP/matrixmanipulation/cat.xml
scilab/modules/elementary_functions/help/pt_BR/matrixmanipulation/cat.xml
scilab/modules/elementary_functions/help/ru_RU/matrixmanipulation/cat.xml

index edcae38..d0cc0c3 100644 (file)
@@ -2,8 +2,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.
           xmlns:scilab="http://www.scilab.org" xml:id="cat" xml:lang="en">
     <refnamediv>
         <refname>cat</refname>
-        <refpurpose>concatenate several arrays</refpurpose>
+        <refpurpose>stacks vectors matrices or arrays into an hypermatrix or hyperarray</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>y=cat(dims,A1,A2,...,An)</synopsis>
+        <synopsis>y = cat(dim, A1, A2, ...,An)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>dims</term>
+                <term>dim</term>
                 <listitem>
-                    <para>a positive real scalar.</para>
+                    <para>
+                        integer>0: index of the dimension along which input arrays must be stacked.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>A1,A2,..An</term>
+                <term>A1, A2,..An</term>
                 <listitem>
-                    <para>scalars, vectors, matrices or multi-arrays, or cell arrays.
-                        <literal>A1,A2,...,An</literal> must have the same size (excluding the dimension number
-                        <literal>dims</literal>). <literal>size(A1,i)=size(A2,i)=...=size(An,i)</literal> for <literal>i</literal> different of dims
-                        and <literal>size(A1,dims), size(A2,dims),...,size(An,dims)</literal> can be
-                        different.
+                    <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>
                 <term>y</term>
                 <listitem>
                     <para>
-                        a scalar, vector, matrix or multi-array, or cell array <literal>y</literal> has the same type
-                        as <literal>A1,A2,...,An</literal>.
+                        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>
     <refsection>
         <title>Description</title>
         <para>
-            <literal>y=cat(dims,A1,A2,...,An)</literal> : <literal>y</literal> is the result of the
-            concatenation of the input arguments <literal>A1,A2,...,An</literal>.
+            <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>
-            If <literal>dims=1</literal>, then the concatenation is done according to the
-            rows
+            <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>A1=[1 2 3 ; 4 5 6]</literal>; <literal>A2=[7 8 9 ; 10 11 12]</literal>; <literal>y=cat(1,A1,A2)</literal> =&gt; <literal>y=[1
-                2 3 ; 4 5 6 ;7 8 9; 10 11 12]
-            </literal>
-            .
-        </para>
-        <para>
-            If <literal>dims=2</literal>, then the concatenation is done according to the columns
-            of the input arguments
-        </para>
-        <para>
-            <literal>A1=[1 2 3;4 5 6]</literal>; <literal>A2=[7 8 9 ;10 11 12]</literal>; <literal>y=cat(2,A1,A2)</literal> =&gt; <literal>y=[1 2
-                3 7 8 9 ; 4 5 6 10 11 12]
-            </literal>
-            .
+            <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[
-// first example : concatenation according to the rows
-dims=1; A1=[1 2 3]; A2=[4 5 6 ; 7 8 9]; A3=[10 11 12]; y=cat(dims,A1,A2,A3)
+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
 
-// second example :  concatenation according to the columns
-dims=2; A1=[1 2 3]'; A2=[4 5;7 8;9 10]; y=cat(dims,A1,A2)
+--> B = uint8(grand(2,4,"uin",0,255))
+ B  =
+  170  182  39  197
+  115  108  16   51
 
-// third example : concatenation according to the 3th dimension
-dims=3; A1=matrix(1:12,[2,2,3]); A2=[13 14;15 16]; A3=matrix(21:36,[2,2,4]); y=cat(dims,A1,A2,A3)
+--> 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>
index e220d44..6422d35 100644 (file)
@@ -1,10 +1,9 @@
 <?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.
  * 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="ja">
-
     <refnamediv>
-
         <refname>cat</refname>
-
         <refpurpose>複数の配列を結合する</refpurpose>
-
     </refnamediv>
-
     <refsynopsisdiv>
-
         <title>呼び出し手順</title>
-
-        <synopsis>y=cat(dims,A1,A2,...,An)</synopsis>
-
+        <synopsis>y = cat(dim, A1, A2, ...,An)</synopsis>
     </refsynopsisdiv>
-
     <refsection>
-
         <title>引数</title>
-
         <variablelist>
-
             <varlistentry>
-
-                <term>dims</term>
-
+                <term>dim</term>
                 <listitem>
-
                     <para>正の実数スカラー.</para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>A1,A2,..An</term>
-
                 <listitem>
-
                     <para>
-
                         スカラー, ベクトル, 行列または多次元配列, またはセル配列.
-
                         <literal>A1,A2,...,An</literal>は
-
-                        (次元<literal>dims</literal>を除き)同じ大きさとなります.
-
-                        <literal>dims</literal>以外の<literal>i</literal>について
-
+                        (次元<literal>dim</literal>を除き)同じ大きさとなります.
+                        <literal>dim</literal>以外の<literal>i</literal>について
                         <literal>size(A1,i)=size(A2,i)=...=size(An,i)</literal>
-
                         であり,
-
-                        <literal>size(A1,dims), size(A2,dims),...,size(An,dims)</literal>
-
+                        <literal>size(A1,dim), size(A2,dim),...,size(An,dim)</literal>
                         は異なる数とすることができます.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>y</term>
-
                 <listitem>
-
                     <para>
-
                         スカラー, ベクトル, 行列またはセル配列, <literal>y</literal> は
-
                         <literal>A1,A2,...,An</literal>と同じ型となります.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
         </variablelist>
-
     </refsection>
-
     <refsection>
-
         <title>説明</title>
-
         <para>
-
-            <literal>y=cat(dims,A1,A2,...,An)</literal>:
-
+            <literal>y=cat(dim,A1,A2,...,An)</literal>:
             <literal>y</literal> は,入力引数<literal>A1,A2,...,An</literal>
-
             を結合したものとなります.
-
         </para>
-
         <para>
-
-            <literal>dims=1</literal>の場合,
-
-            結合は行方向に行われます.
-
+            <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>A1=[1 2 3 ; 4 5 6]</literal>; <literal>A2=[7 8 9 ; 10 11 12]</literal>; <literal>y=cat(1,A1,A2)</literal> =&gt; <literal>y=[1
-
-                2 3 ; 4 5 6 ;7 8 9; 10 11 12]
-
-            </literal>
-
-            .
-
-        </para>
-
-        <para>
-
-            <literal>dims=2</literal>の場合,結合は入力引数の列方向に行われます,...
-
-        </para>
-
-        <para>
-
-            <literal>A1=[1 2 3;4 5 6]</literal>; <literal>A2=[7 8 9 ;10 11 12]</literal>; <literal>y=cat(2,A1,A2)</literal> =&gt; <literal>y=[1 2
-
-                3 7 8 9 ; 4 5 6 10 11 12]
-
-            </literal>
-
-            .
-
+            <literal>cat()</literal> is useful mainly for <literal>dim > 2</literal>, to build an
+            hypermatrix or hypercell.
         </para>
-
     </refsection>
-
     <refsection>
-
         <title>例</title>
-
+        <para>Example #1: Building a vector along dim #3</para>
         <programlisting role="example"><![CDATA[
-// first example : concatenation according to the rows
-dims=1; A1=[1 2 3]; A2=[4 5 6 ; 7 8 9]; A3=[10 11 12]; y=cat(dims,A1,A2,A3)
-// second example :  concatenation according to the columns
-dims=2; A1=[1 2 3]'; A2=[4 5;7 8;9 10]; y=cat(dims,A1,A2)
-// third example : concatenation according to the 3th dimension
-dims=3; A1=matrix(1:12,[2,2,3]); A2=[13 14;15 16]; A3=matrix(21:36,[2,2,4]); y=cat(dims,A1,A2,A3)
+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>参照</title>
-
         <simplelist type="inline">
             <member>
                 <link linkend="brackets">brackets [..]</link>
@@ -186,22 +180,12 @@ dims=3; A1=matrix(1:12,[2,2,3]); A2=[13 14;15 16]; A3=matrix(21:36,[2,2,4]); y=c
             <member>
                 <link linkend="lstcat">lstcat</link>
             </member>
-
             <member>
-
                 <link linkend="permute">permute</link>
-
             </member>
-
             <member>
-
                 <link linkend="matrix">matrix</link>
-
             </member>
-
         </simplelist>
-
     </refsection>
-
-</refentry>
-
+</refentry>
\ No newline at end of file
index 4b2464a..fdeeaf6 100644 (file)
@@ -1,9 +1,9 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?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.
     </refnamediv>
     <refsynopsisdiv>
         <title>Seqüência de Chamamento</title>
-        <synopsis>y=cat(dims,A1,A2,...,An)</synopsis>
+        <synopsis>y = cat(dim, A1, A2,..., An)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Parâmetros</title>
         <variablelist>
             <varlistentry>
-                <term>dims</term>
+                <term>dim</term>
                 <listitem>
                     <para>um escalar real positivo </para>
                 </listitem>
@@ -39,8 +39,8 @@
                 <listitem>
                     <para>escalares, vetores, matrizes, multi-arrays ou cell arrays. A1,
                         A2, ..., An, devem ter o mesmo tamanho (excluindo o número de
-                        dimensão dims). size(A1,i)=size(A2,i)=...=size(An,i) para i
-                        diferente de dims e size(A1,dims), size(A2,dims),...,size(An,dims)
+                        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>
     <refsection>
         <title>Descrição</title>
         <para>
-            <literal>y=cat(dims,A1,A2,...,An) :</literal> y é o resutado da
-            concatenação dos argumentos de entrada A1, A2, ..., An. Se dims= 1, então
-            a concatenação é feita de acordo com as linhas; se dims= 2, então a
+            <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>Se dims= 1,então a concatenação é feita de acordo com as
-            linhas
-        </para>
-        <para>A1=[1 2 3 ; 4 5 6]; A2=[7 8 9 ; 10 11 12]; y=cat(1,A1,A2) =&gt; y=[1
-            2 3 ; 4 5 6 ;7 8 9; 10 11 12]
-        </para>
-        <para>Se dims= 2,então a concatenação é feita de acordo com as colunas dos
-            argumentos de entrada
+        <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>A1=[1 2 3;4 5 6]; A2=[7 8 9 ;10 11 12]; y=cat(2,A1,A2) =&gt; y=[1 2
-            3 7 8 9 ; 4 5 6 10 11 12]
+        <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[
-// primeiro exemplo: concatenação de acordo com as linhas
-dims=1; A1=[1 2 3]; A2=[4 5 6 ; 7 8 9]; A3=[10 11 12]; y=cat(dims,A1,A2,A3)
+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
 
-// segundo exemplo: concatenação de acordo com as colunas
-dims=2; A1=[1 2 3]'; A2=[4 5;7 8;9 10]; y=cat(dims,A1,A2)
+--> G = uint8(grand(2,4,"uin",0,255))
+ G  =
+  255  246  104  89
+  152   71  112  17
 
-// terceiro exemplo concatenação de acordo com a terceira dimensão
-dims=3; A1=matrix(1:12,[2,2,3]); A2=[13 14;15 16]; A3=matrix(21:36,[2,2,4]); y=cat(dims,A1,A2,A3)
+--> 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>
index f3b29ca..7886f63 100644 (file)
@@ -2,8 +2,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.
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
-        <synopsis>y=cat(dims,A1,A2,...,An)</synopsis>
+        <synopsis>y = cat(dim, A1, A2,...,An)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
         <variablelist>
             <varlistentry>
-                <term>dims</term>
+                <term>dim</term>
                 <listitem>
                     <para>положительный вещественный скаляр.</para>
                 </listitem>
@@ -39,9 +39,9 @@
                 <listitem>
                     <para>скаляры, векторы, матрицы или многомерные массивы или cell-массивы.
                         A1,A2,...,An должны быть одинакового размера (за исключением номера размерности
-                        <literal>dims</literal>). <literal>size(A1,i)=size(A2,i)=...=size(An,i)</literal> для
-                        <literal>i</literal>, отличных от <literal>dims</literal>,
-                        а <literal>size(A1,dims), size(A2,dims),..., size(An,dims)</literal> могут различаться.
+                        <literal>dim</literal>). <literal>size(A1,i)=size(A2,i)=...=size(An,i)</literal> для
+                        <literal>i</literal>, отличных от <literal>dim</literal>,
+                        а <literal>size(A1,dim), size(A2,dim),..., size(An,dim)</literal> могут различаться.
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Описание</title>
         <para>
-            <literal>y=cat(dims,A1,A2,...,An) :</literal><literal>y</literal> является результатом
+            <literal>y=cat(dim,A1,A2,...,An) :</literal><literal>y</literal> является результатом
             конкатенации входных аргументов <literal>A1, A2,..., An</literal>.
         </para>
         <para>
-            Если <literal>dims=1</literal>, то конкатенация проводится по строкам входных аргументов
-        </para>
-        <para>
-            <literal>A1=[1 2 3 ; 4 5 6]</literal>; <literal>A2=[7 8 9 ; 10 11 12]</literal>;
-           <literal>y=cat(1,A1,A2)</literal>  =&gt; <literal>y=[1 2 3 ; 4 5 6 ;7 8 9; 10 11 12]</literal>.
-        </para>
-        <para>
-            Если <literal>dims=2</literal>, то конкатенация проводится по столбцам входных аргументов
+            <literal>cat(1, A1, A2, A3)</literal> эквивалентно <literal>[A1 ; A2 ; A3]</literal>.
+            <literal>cat(2, A1, A2, A3)</literal> эквивалентно <literal>[A1 A2 A3]</literal>.
+            Квадратные скобки работают быстрее и гораздо предпочтительней в обоих случаях.
         </para>
         <para>
-            <literal>A1=[1 2 3 ; 4 5 6]</literal>; <literal>A2=[7 8 9 ; 10 11 12]</literal>;
-            <literal>y=cat(2,A1,A2)</literal> =&gt; <literal>y=[1 2 3 7 8 9 ; 4 5 6 10 11 12]
-            </literal>
-            .
+            <literal>cat()</literal> полезна главным образом для <literal>dim > 2</literal>, чтобы построить
+            гиперматрицу или cell-гипермассив.
         </para>
     </refsection>
     <refsection>
         <title>Примеры</title>
+        <para>Пример №1: построение вектора вдоль размерности №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>Пример №2: Построение матрицы текста размером size(1,3,2):</para>
         <programlisting role="example"><![CDATA[
-// первый пример: конкатенация по строкам
-dims=1; A1=[1 2 3]; A2=[4 5 6 ; 7 8 9]; A3=[10 11 12]; y=cat(dims,A1,A2,A3)
+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>Пример №3: Упаковка отдельных слоёв R G B в мини-картинку RGB:</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
 
-// второй пример: конкатенация по столбцам
-dims=2; A1=[1 2 3]'; A2=[4 5;7 8;9 10]; y=cat(dims,A1,A2)
+--> G = uint8(grand(2,4,"uin",0,255))
+ G  =
+  255  246  104  89
+  152   71  112  17
 
-// третий пример: конкатенация по третьей размерности
-dims=3; A1=matrix(1:12,[2,2,3]); A2=[13 14;15 16]; A3=matrix(21:36,[2,2,4]); y=cat(dims,A1,A2,A3)
+--> 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>Пример №4: Построение cell-гипермассива:</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>Смотрите также</title>