permute(): now supports rationals. UTests + help page overhauled 41/18441/10
Samuel GOUGEON [Wed, 10 Aug 2016 23:29:02 +0000 (01:29 +0200)]
Change-Id: Ibe4ee975eccb5b8dfb0a6047c2e6db9131db15a9

scilab/CHANGES.md
scilab/modules/elementary_functions/help/en_US/matrixmanipulation/permute.xml
scilab/modules/elementary_functions/help/fr_FR/matrixmanipulation/permute.xml [new file with mode: 0644]
scilab/modules/elementary_functions/help/ja_JP/matrixmanipulation/permute.xml [deleted file]
scilab/modules/elementary_functions/help/pt_BR/matrixmanipulation/permute.xml [deleted file]
scilab/modules/elementary_functions/help/ru_RU/matrixmanipulation/permute.xml
scilab/modules/elementary_functions/macros/permute.sci
scilab/modules/elementary_functions/tests/unit_tests/permute.dia.ref
scilab/modules/elementary_functions/tests/unit_tests/permute.tst

index 7ccc6cd..2879a4f 100644 (file)
@@ -144,9 +144,10 @@ Feature changes and additions
   - option "tigh_limits" added,
   - Any handle having some Axes as direct children -- as uicontrol-frame -- is now supported.
 * `householder` can now return the reflection matrix, and has a demo.
-* `ndgrid` can now works with any types of homogeneous data.
-* `bench_run` can now return its results and/or record them in a file.
-* `typeof(.., "overload")` allows now to get the overloading type-code of an object.
+* `ndgrid` can now works with any types of homogeneous data
+* `permute` now supports arrays of rationals.
+* `bench_run` can now return its results and/or record them in a file
+* `typeof(.., "overload")` allows now to get the overloading type-code of an object
 * `sign` can now handle a sparse matrix.
 * `sleep(..,'s')` allows now to specify the duration in seconds.
 * `real`, `imag`, `conj` and `isreal` now accept rational fractions.
@@ -208,7 +209,7 @@ Help pages:
 -----------
 
 * fixed / improved:  `members`, `part`, `ode`, `ode_optional_output`, `ode_roots`, `plot2d`, `roots`,
-  `printf`, `sprintf`, `iconvert`, `stdev`, `xlabel`, `and_op`, `or_op`, `tree2code`, `%helps`,
+  `printf`, `sprintf`, `iconvert`, `stdev`, `xlabel`, `and_op`, `or_op`, `permute`, `tree2code`, `%helps`,
   `scilab|scilex`, `flipdim`
 * rewritten: `consolebox`, `double`, `isoview`, `pixel_drawing_mode`, `householder`, `or`, `and`, `format`, `typeof`,
 `brackets`, `setlanguage`, `sleep`, `isinf`, `bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`
@@ -219,7 +220,7 @@ Help pages:
   - Signal processing: New `Convolution - correlation` subsection. `wfir_gui`, `filt_sinc`, `hilb`, `fft2`, `fftshift`,`ifftshift`, `hilbert`, `cepstrum`, `conv`, `conv2`, `convol2d`, `xcor`, `corr`, `hank`, `mrfit`, `frfir` sorted up in existing subsections.
   - Colormaps and GUI/Menus subsections created
 * translations added:
-  - (fr): `format`, `typeof`, `isoview`, `ndgrid`, `bench_run`, `consolebox`, `harmean`, `sleep`, `strtod`
+  - (fr): `format`, `typeof`, `isoview`, `ndgrid`, `bench_run`, `consolebox`, `harmean`, `sleep`, `strtod`, `permute`
   - (ru): homepage
 
 
index 3707b12..b2e7d50 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA - Farid BELAHCENE
+ * Copyright (C) 2016 - Samuel GOUGEON
  *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * 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="permute" xml:lang="en">
+<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="permute" xml:lang="en">
     <refnamediv>
         <refname>permute</refname>
         <refpurpose>permutes the dimensions of an array</refpurpose>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
+                <term>x</term>
+                <listitem>
+                    <para>
+                      an array with any number of dimensions (0, 1, 2, or any number n>2),
+                      of any data type: booleans, integers, decimal real or complex numbers,
+                      polynomials, rationals, array of structures, array of cells.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
                 <term>dims</term>
                 <listitem>
-                    <para>a scalar or a vector of positive reals.</para>
+                    <para>
+                      a valid permutation of 1:n>=nmin where n is the number of dimensions of
+                      the desired array, at least as many as  <literal>nmin = ndims(x)</literal>.
+                    </para>
+                    <para>
+                      The dimension <literal>#i</literal> in <literal>y</literal> was the dimension
+                      <literal>#dims(i)</literal> in <literal>x</literal>.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>x</term>
+                <term>y</term>
                 <listitem>
-                    <para>a scalar, a vector, a matrix or a multi-array.</para>
+                    <para>
+                      an array with the contents of <literal>x</literal>,
+                      with identical but permuted sizes.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            Permutes the dimensions of an array according to <varname>dims</varname>.
-        </para>
-        <para>
-            Input argument <varname>dims</varname> must be a valid permutation, such as
-            the dimension <literal>#i</literal> becomes the dimension <literal>#dims(i)</literal>.
+            Permutes the dimensions of the array according to <varname>dims</varname>.
         </para>
+        <important>
+             Any trailing dimension of the result <literal>y</literal> that becomes a singleton
+             (has a new size equal to 1, coming from a formerly non trailing singleton dimension)
+             is automatically ignored (squeezed).
+         </important>
+         <note>
+             <literal>permute()</literal> is mainly interesting when dealing with hypermatrices.
+             To only transpose a matrix (permute its rows into columns and vice-versa), the
+             <literal>.'</literal> or <literal>'</literal> operators should be prefered.
+         </note>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-//example 1:
-x = [1 2 3;4 5 6]
-y = permute(x,[2 1])
-
-//example 2:
-x = matrix(1:12,[2,3,2])
+// Example 1: A matrix becomes an hypermatrix with one side of size==1
+//            (here the number of rows)
+x = [1 2 3; 4 5 6]
 y = permute(x,[3 1 2])
+ ]]></programlisting>
+    <screen><![CDATA[--> x = [1 2 3; 4 5 6]
+ x  =
+   1.   2.   3.
+   4.   5.   6.
+
+--> y = permute(x,[3 1 2])
+ y  =
+(:,:,1)
+   1.   4.
+(:,:,2)
+   2.   5.
+(:,:,3)
+   3.   6.
+]]></screen>
+        <programlisting role="example"><![CDATA[
+// Example 2: With encoded integers
+x = int8(matrix(1:24, [3 4 2]))
+y = permute(x, [2 3 1])
+ ]]></programlisting>
+    <screen><![CDATA[--> x = int8(matrix(1:24, [3 4 2]))
+ x  =
+(:,:,1)
+  1  4  7  10
+  2  5  8  11
+  3  6  9  12
+(:,:,2)
+  13  16  19  22
+  14  17  20  23
+  15  18  21  24
 
-x = matrix(1:12, [3 2 2])
-y = permute(x, [3 4 1 2])
-// Dimensions are changed according to dims
-// #1=rows    becomes #3=pages
-// #2=columns becomes #4=books
-// #3=pages   becomes #1=rows
-// #4=books   becomes #2=columns
+--> y = permute(x, [2 3 1])
+ y  =
+(:,:,1)
+  1  13
+  4  16
+  7  19
+ 10  22
+(:,:,2)
+  2  14
+  5  17
+  8  20
+ 11  23
+(:,:,3)
+  3  15
+  6  18
+  9  21
+ 12  24
+]]></screen>
+        <programlisting role="example"><![CDATA[
+// Example 3:
+x = matrix(1:8, [2 1 4])
+y = permute(x, [3 1 2]);
+// The dimension 1 was the 3rd: size = 4 = new number of rows
+// The dimension 2 was the 1st: size = 2 = new number of columns
+// The dimension 3 was the 2sd: size = 1 = new number of pages
+y
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -79,8 +155,22 @@ y = permute(x, [3 4 1 2])
                 <link linkend="quote">quote</link>
             </member>
             <member>
-                <link linkend="cat">cat</link>
+                <link linkend="ndims">ndims</link>
+            </member>
+            <member>
+                <link linkend="squeeze">squeeze</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    Extension to rationals
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/elementary_functions/help/fr_FR/matrixmanipulation/permute.xml b/scilab/modules/elementary_functions/help/fr_FR/matrixmanipulation/permute.xml
new file mode 100644 (file)
index 0000000..233824e
--- /dev/null
@@ -0,0 +1,178 @@
+<?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) 2016 - Samuel GOUGEON
+ *
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ *
+ * 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="permute" xml:lang="en">
+    <refnamediv>
+        <refname>permute</refname>
+        <refpurpose>permute les dimensions d'un tableau à N dimensions</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Syntaxe</title>
+        <synopsis>y = permute(x, dims)</synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>x</term>
+                <listitem>
+                    <para>Un tableau ayant un nombre quelconque N de dimensions  (0, 1, 2, ou N>2),
+                      de type de données quelconque : booléens, entiers encodés, nombres décimaux
+                      réels ou complexes, polynômes, fractions rationnelles, tableau de structures,
+                      tableau de cells.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>dims</term>
+                <listitem>
+                    <para>
+                      toute permutation des nombres entiers 1:N où N>=Nmin est le nombre de
+                      dimensions du tableau souhaité, a minima <literal>nmin = ndims(x)</literal>.
+                    </para>
+                    <para>
+                     La dimension numéro <literal>#i</literal> dans <literal>y</literal> était la
+                     dimension numéro <literal>#dims(i)</literal> dans <literal>x</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>y</term>
+                <listitem>
+                    <para>
+                      Un tableau ayant le même contenu que <literal>x</literal>, avec des tailles
+                      identiques à celles de <literal>x</literal>  mais permutées.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            <literal>permute(..)</literal> permute les dimensions du tableau  selon les correspondances
+            données dans le vecteur <varname>dims</varname>.
+        </para>
+        <important>
+             Dans le tableau résultant <literal>y</literal>, toute dimension d'ordre majeur réduite
+             à une taille de 1 (singleton) est automatiquement ignorée (réduction).
+         </important>
+         <note>
+             <literal>permute()</literal> est une généralisation à un nombre de dimensions N
+             quelconque des opérateurs de transposition <literal>.'</literal> ou <literal>'</literal>.
+             Elle est principalement utile pour manipuler les dimensions des hypermatrices.
+             Pour simplement transposer une matrice (permuter ses lignes en colonnes et vice-versa),
+             on utilisera de préférence <literal>.'</literal> ou <literal>'</literal>
+         </note>
+    </refsection>
+    <refsection>
+        <title>Exemples</title>
+        <programlisting role="example"><![CDATA[
+// Exemple 1 : Une matrice devient une hypermatrice avec un coté de taille == 1
+//             (ici le nombre de lignes (dans chaque page)
+x = [1 2 3; 4 5 6]
+y = permute(x,[3 1 2])
+ ]]></programlisting>
+    <screen><![CDATA[--> x = [1 2 3; 4 5 6]
+ x  =
+   1.   2.   3.
+   4.   5.   6.
+
+--> y = permute(x,[3 1 2])
+ y  =
+(:,:,1)
+   1.   4.
+(:,:,2)
+   2.   5.
+(:,:,3)
+   3.   6.
+]]></screen>
+        <programlisting role="example"><![CDATA[
+// Exemple 2 : avec des entiers encodés
+x = int8(matrix(1:24, [3 4 2]))
+y = permute(x, [2 3 1])
+ ]]></programlisting>
+    <screen><![CDATA[--> x = int8(matrix(1:24, [3 4 2]))
+ x  =
+(:,:,1)
+  1  4  7  10
+  2  5  8  11
+  3  6  9  12
+(:,:,2)
+  13  16  19  22
+  14  17  20  23
+  15  18  21  24
+
+--> y = permute(x, [2 3 1])
+ y  =
+(:,:,1)
+  1  13
+  4  16
+  7  19
+ 10  22
+(:,:,2)
+  2  14
+  5  17
+  8  20
+ 11  23
+(:,:,3)
+  3  15
+  6  18
+  9  21
+ 12  24
+]]></screen>
+        <programlisting role="example"><![CDATA[
+// Exemple 3 :
+x = matrix(1:8, [2 1 4])
+y = permute(x, [3 1 2]);
+// La dimension 1 était la 3ème : taille = 4 = nouveau nombre de lignes
+// La dimension 2 était la 1ère : taille = 2 = nouveau nombre de colonnes
+// La dimension 3 était la 2ème : taille = 1 = nouveau nombre de pages
+y
+ ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>Voir aussi</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="pertrans">pertrans</link>
+            </member>
+            <member>
+                <link linkend="quote">quote</link>
+            </member>
+            <member>
+                <link linkend="ndims">ndims</link>
+            </member>
+            <member>
+                <link linkend="squeeze">squeeze</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>Historique</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    Extension aux tableaux de fractions rationnelles
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/elementary_functions/help/ja_JP/matrixmanipulation/permute.xml b/scilab/modules/elementary_functions/help/ja_JP/matrixmanipulation/permute.xml
deleted file mode 100644 (file)
index afdb155..0000000
+++ /dev/null
@@ -1,126 +0,0 @@
-<?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
- *
- * 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="permute" xml:lang="ja">
-
-    <refnamediv>
-
-        <refname>permute</refname>
-
-        <refpurpose>配列の次元の順序を変更</refpurpose>
-
-    </refnamediv>
-
-    <refsynopsisdiv>
-
-        <title>呼び出し手順</title>
-
-        <synopsis>y=permute(x,dims)</synopsis>
-
-    </refsynopsisdiv>
-
-    <refsection>
-
-        <title>引数</title>
-
-        <variablelist>
-
-            <varlistentry>
-
-                <term>dims</term>
-
-                <listitem>
-
-                    <para>正の実数のスカラーまたはベクトル</para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>x</term>
-
-                <listitem>
-
-                    <para>スカラー,ベクトル,行列または多次元配列.</para>
-
-                </listitem>
-
-            </varlistentry>
-
-        </variablelist>
-
-    </refsection>
-
-    <refsection>
-
-        <title>説明</title>
-
-        <para>
-
-            <literal>配列の次元の順序を変更します.</literal>
-
-        </para>
-
-    </refsection>
-
-    <refsection>
-
-        <title>例</title>
-
-        <programlisting role="example"><![CDATA[
-//例 1:
-x=[1 2 3;4 5 6];
-y=permute(x,[2 1]);
-//例 2:
-x=matrix(1:12,[2,3,2]);
-y=permute(x,[3 1 2]);
- ]]></programlisting>
-
-    </refsection>
-
-    <refsection role="see also">
-
-        <title>参照</title>
-
-        <simplelist type="inline">
-
-            <member>
-
-                <link linkend="pertrans">pertrans</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="quote">quote</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="cat">cat</link>
-
-            </member>
-
-        </simplelist>
-
-    </refsection>
-
-</refentry>
-
diff --git a/scilab/modules/elementary_functions/help/pt_BR/matrixmanipulation/permute.xml b/scilab/modules/elementary_functions/help/pt_BR/matrixmanipulation/permute.xml
deleted file mode 100644 (file)
index 55724d1..0000000
+++ /dev/null
@@ -1,74 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2008 - INRIA - Farid BELAHCENE
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * 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="permute" xml:lang="pt">
-    <refnamediv>
-        <refname>permute</refname>
-        <refpurpose>permuta as dimensões de um array</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-        <synopsis>y=permute(x,dims)</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Parâmetros</title>
-        <variablelist>
-            <varlistentry>
-                <term>dims</term>
-                <listitem>
-                    <para>um escalar ou um vetor de números reais positivos </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>x</term>
-                <listitem>
-                    <para>um escalar, um vetor, uma matriz ou um multi-array</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descrição</title>
-        <para>
-            <literal>y=permute(x,dims) : </literal>
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[
-//exemplo 1:
-x=[1 2 3;4 5 6];
-y=permute(x,[2 1]);
-
-//exemplo 2:
-x=matrix(1:12,[2,3,2]);
-y=permute(x,[3 1 2]);
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>Ver Também</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="pertrans">pertrans</link>
-            </member>
-            <member>
-                <link linkend="quote">quote</link>
-            </member>
-            <member>
-                <link linkend="cat">cat</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
index e014335..d4bf1c0 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2008 - INRIA - Farid BELAHCENE
+ * Copyright (C) 2016 - Samuel GOUGEON
  *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * 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="permute" xml:lang="ru">
+<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="permute" xml:lang="ru">
     <refnamediv>
         <refname>permute</refname>
-        <refpurpose>перестановка размерностей массива</refpurpose>
+        <refpurpose>переставляет размерности массива</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
-        <synopsis>y=permute(x,dims)</synopsis>
+        <synopsis>y = permute(x, dims)</synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Аргументы</title>
         <variablelist>
             <varlistentry>
+                <term>x</term>
+                <listitem>
+                    <para>
+                      массив с любым числом размерностей (0, 1, 2 или  любым числом n>2) любого типа
+                      данных: логических, целочисленных десятичных вещественных  или комплексных
+                      чисел, полиномов, рациональных значений, массива структур, cell-массива.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
                 <term>dims</term>
                 <listitem>
-                    <para>скаляр или вектор положительных вещественных чисел.</para>
+                    <para>
+                      допустимая перестановка <literal>1:n>=nmin</literal>, где <literal>n</literal>
+                      - это количество размерностей желаемого массива, по меньшей мере
+                      <literal>nmin = ndims(x)</literal>.
+                    </para>
+                    <para>
+                      Размерность <literal>#i</literal> в <varname>y</varname> была размерностью
+                      <literal>#dims(i)</literal> в <varname>x</varname>.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>x</term>
+                <term>y</term>
                 <listitem>
-                    <para>скаляр, вектор, матрица или многомерный массив.</para>
+                    <para>
+                      массив, у которого содержимое массива <varname>x</varname>,  с одинаковыми,
+                      не переставленными размерами.
+                    </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Описание</title>
         <para>
-            <literal>Перестановка размерностей массива.</literal>
+            Переставляет размерности массива согласно <varname>dims</varname>.
         </para>
+        <important>
+             Любые размерности в конце последовательности результата <varname>y</varname>, которые
+             оказываются одноэлементным множеством (имеют новый размер равный 1, произошедший из
+             предыдущей размерности неединичного размера не в конце последовательности),
+             автоматически игнорируются (удаляются).
+         </important>
+         <note>
+             Главным образом <code>permute()</code> представляет интерес, когда идёт работа с
+             гиперматрицами. Чтобы просто транспонировать матрицу (переставить местами их
+             строки и столбцы и наоборот), то лучше использовать операторы <literal>.
+             '</literal> или <literal>'</literal>.
+         </note>
     </refsection>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[
-//Пример 1:
-x=[1 2 3; 4 5 6];
-y=permute(x,[2 1]);
+// Пример 1: матрица становится гиперматрицей, одна сторона которой имеет размер
+//           равный единице (здесь количество строк)
+x = [1 2 3; 4 5 6]
+y = permute(x,[3 1 2])
+ ]]></programlisting>
+    <screen><![CDATA[--> x = [1 2 3; 4 5 6]
+ x  =
+   1.   2.   3.
+   4.   5.   6.
+
+--> y = permute(x,[3 1 2])
+ y  =
+(:,:,1)
+   1.   4.
+(:,:,2)
+   2.   5.
+(:,:,3)
+   3.   6.
+]]></screen>
+        <programlisting role="example"><![CDATA[
+// Пример 2: С закодированными целыми числами
+x = int8(matrix(1:24, [3 4 2]))
+y = permute(x, [2 3 1])
+ ]]></programlisting>
+    <screen><![CDATA[--> x = int8(matrix(1:24, [3 4 2]))
+ x  =
+(:,:,1)
+  1  4  7  10
+  2  5  8  11
+  3  6  9  12
+(:,:,2)
+  13  16  19  22
+  14  17  20  23
+  15  18  21  24
 
-//пример 2:
-x=matrix(1:12,[2, 3, 2]);
-y=permute(x,[3 1 2]);
+--> y = permute(x, [2 3 1])
+ y  =
+(:,:,1)
+  1  13
+  4  16
+  7  19
+ 10  22
+(:,:,2)
+  2  14
+  5  17
+  8  20
+ 11  23
+(:,:,3)
+  3  15
+  6  18
+  9  21
+ 12  24
+]]></screen>
+        <programlisting role="example"><![CDATA[
+// Пример 3:
+x = matrix(1:8, [2 1 4])
+y = permute(x, [3 1 2]);
+// Размерность 1 была третьей: размер = 4 = новое количество строк
+// Размерность 2 была первой: размер = 2 = новое количество строк
+// Размерность 3 была второй: размер = 1 = новое количество страниц
+y
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -67,8 +158,22 @@ y=permute(x,[3 1 2]);
                 <link linkend="quote">quote</link>
             </member>
             <member>
-                <link linkend="cat">cat</link>
+                <link linkend="ndims">ndims</link>
+            </member>
+            <member>
+                <link linkend="squeeze">squeeze</link>
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    Расширение для рациональных значений.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
index 8f2bd8b..d393db9 100644 (file)
@@ -1,6 +1,6 @@
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 // Copyright (C) INRIA - Farid BELAHCENE
-// Copyright (C) 2013 - Samuel GOUGEON : processing rewritten, fixing http://bugzilla.scilab.org/5205
+// Copyright (C) 2013, 2016 - Samuel GOUGEON
 //
 // Copyright (C) 2012 - 2016 - Scilab Enterprises
 //
@@ -19,21 +19,27 @@ function y = permute(x, dims)
     // -dims a vector which contains the permutation order
     // Output :
     // -y the result of the x permutation
+    // History:
+    // 2013 - S. GOUGEON : processing rewritten, fixing http://bugzilla.scilab.org/5205
+    // 2016 - S. GOUGEON : extension to rationals
 
-    // Verify input arguments number
+    if x==[] then
+        y = []
+        return
+    end
+
+    // CHECKING ARGUMENTS
+    // ------------------
     if argn(2) <> 2 then
-        error(msprintf(gettext("%s: Wrong number of input argument(s): %d expected.\n"), "permute", 2));
+        msg = gettext("%s: Wrong number of input argument(s): %d expected.\n")
+        error(msprintf(msg, "permute", 2));
     end
 
     // Verify if the size of dims corresponds to dimension of x
-    if ndims(dims) <> 2 then
-        error(msprintf(gettext("%s: Wrong size for argument #%d: Vector expected.\n"), "permute", 2));
-
-    elseif or(gsort(dims,"c","i") <> (1:prod(size(dims)))) then
-        error(msprintf(gettext("%s: Wrong value for input argument #%d: Must be a valid permutation vector.\n"), "permute", 2));
-
-    elseif prod(size(dims)) < ndims(x) then
-        error(msprintf(gettext("%s: Wrong size for input argument #%d: At least the size of input argument #%d expected.\n"), "permute", 2, 1));
+    if ~(or(type(dims)==[1 8]) && and(int(dims)==dims) && ..
+        and(gsort(dims(:)',"g","i")==(1:max(length(dims),ndims(x))))) then
+        msg = _("%s: Wrong value for input argument #%d: Must be a valid permutation of [1..n>%d] integers.\n")
+        error(msprintf(msg, "permute", 2, ndims(x)-1));
     end
 
     // Case x is empty
@@ -76,7 +82,13 @@ function y = permute(x, dims)
             y{LI2(i)} = x{LI(i)};
         end
     else
-        y(LI2) = x(LI)
+        if typeof(x)~="rational"
+            y(LI2) = x(LI)
+        else
+            y = x
+            y.num(LI2) = x.num(LI)
+            y.den(LI2) = x.den(LI)
+        end
         y = matrix(y, s)
     end
 
index 0ffceb8..1ba306f 100644 (file)
@@ -1,58 +1,94 @@
 // =============================================================================
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 // Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
+// Copyright (C) 2016 - Samuel GOUGEON
 //
 //  This file is distributed under the same license as the Scilab package.
 // =============================================================================
 //
 // <-- CLI SHELL MODE -->
 //
+
 // With a real matrix
 x = [1 2 3; 4 5 6];
 y = permute(x, [2 1]);
 assert_checkequal(y, x');
+
 // With an integer matrix
 x = int32(x);
 y = permute(x, [2 1]);
 assert_checkequal(y, x');
+
 // With a string matrix
 x = string(x);
 y = permute(x, [2 1]);
 assert_checkequal(y, x');
+
 // With a complex matrix
 x = [1 2 3; 4 5 6]*%i;
 y = permute(x, [2 1]);
 refY = [1 4; 2 5; 3 6]*%i;
 assert_checkequal(y, refY);
+
 // With a real hypermatrix
-x = matrix(1:12, [2, 3, 2]);
-y = permute(x, [3 1 2]);
+x0 = matrix(1:12, [2, 3, 2]);
+y = permute(x0, [3 1 2]);
 clear refY
 refY(:, :, 1) = [1 2; 7 8];
 refY(:, :, 2) = [3 4; 9 10];
 refY(:, :, 3) = [5 6; 11 12];
+refY0 = refY;
+assert_checkequal(y, refY);
+
+// With a boolean hypermatrix
+x = x0<5;
+y = permute(x, [3 1 2]);
+refY = refY0<5;
 assert_checkequal(y, refY);
+
 // With an integer hypermatrix
-x = int32(x);
+x = int32(x0);
 y = permute(x, [3 1 2]);
-refY = int32(refY);
+refY = int32(refY0);
 assert_checkequal(y, refY);
+
 // With a string hypermatrix
-x = string(x);
+x = string(x0);
 y = permute(x, [3 1 2]);
-refY = string(refY);
+refY = string(refY0);
 assert_checkequal(y, refY);
+
 // With a complex hypermatrix
-x = matrix(1:12, [2, 3, 2])*%i;
+x = x0*%i;
 y = permute(x, [3 1 2]);
-clear refY
-refY(:, :, 1) = [1 2; 7 8]*%i;
-refY(:, :, 2) = [3 4; 9 10]*%i;
-refY(:, :, 3) = [5 6; 11 12]*%i;
+refY = refY0*%i;
+assert_checkequal(y, refY);
+
+// With an hypermatrix of polynomials
+x = 1 + x0*%z;
+y = permute(x, [3 1 2]);
+refY = 1 + refY0*%z;
+assert_checkequal(y, refY);
+
+// With an hypermatrix of rationals
+x = (1 + x0*%z)./(1 - x0*%z);
+y = permute(x, [3 1 2]);
+refY = (1 + refY0*%z) ./ (1 - refY0*%z);
 assert_checkequal(y, refY);
+
+// With an array of structures
+s(3,4,2).r = %pi;
+ss = size(s);
+ps = permute(s,[2 3 1]);
+assert_checkequal(size(ps),ss([2 3 1]));
+assert_checkequal(ps(24).r, %pi);
+
+
 // Error checks
-refMsg = msprintf(_("%s: Wrong size for input argument #%d: At least the size of input argument #%d expected.\n"), "permute", 2, 1);
+// ------------
+msg = _("%s: Wrong value for input argument #%d: Must be a valid permutation of [1..n>%d] integers.\n");
+refMsg = msprintf(msg, "permute", 2, 2);
 assert_checkerror("permute(x, [1 2]);", refMsg);
-refMsg = msprintf(_("%s: Wrong value for input argument #%d: Must be a valid permutation vector.\n"), "permute", 2);
 assert_checkerror("permute(x, [1 2 4]);", refMsg);
+assert_checkerror("permute(x, [1 3.1 2]);", refMsg);
 assert_checkerror("permute(x, [1 2 3 5]);", refMsg);
index 67043dd..1ba306f 100644 (file)
@@ -1,6 +1,7 @@
 // =============================================================================
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 // Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
+// Copyright (C) 2016 - Samuel GOUGEON
 //
 //  This file is distributed under the same license as the Scilab package.
 // =============================================================================
 // With a real matrix
 x = [1 2 3; 4 5 6];
 y = permute(x, [2 1]);
-
 assert_checkequal(y, x');
 
 // With an integer matrix
 x = int32(x);
 y = permute(x, [2 1]);
-
 assert_checkequal(y, x');
 
 // With a string matrix
 x = string(x);
 y = permute(x, [2 1]);
-
 assert_checkequal(y, x');
 
 // With a complex matrix
 x = [1 2 3; 4 5 6]*%i;
 y = permute(x, [2 1]);
 refY = [1 4; 2 5; 3 6]*%i;
-
 assert_checkequal(y, refY);
 
 // With a real hypermatrix
-x = matrix(1:12, [2, 3, 2]);
-y = permute(x, [3 1 2]);
+x0 = matrix(1:12, [2, 3, 2]);
+y = permute(x0, [3 1 2]);
 clear refY
 refY(:, :, 1) = [1 2; 7 8];
 refY(:, :, 2) = [3 4; 9 10];
 refY(:, :, 3) = [5 6; 11 12];
+refY0 = refY;
+assert_checkequal(y, refY);
 
+// With a boolean hypermatrix
+x = x0<5;
+y = permute(x, [3 1 2]);
+refY = refY0<5;
 assert_checkequal(y, refY);
 
 // With an integer hypermatrix
-x = int32(x);
+x = int32(x0);
 y = permute(x, [3 1 2]);
-refY = int32(refY);
-
+refY = int32(refY0);
 assert_checkequal(y, refY);
 
 // With a string hypermatrix
-x = string(x);
+x = string(x0);
 y = permute(x, [3 1 2]);
-refY = string(refY);
-
+refY = string(refY0);
 assert_checkequal(y, refY);
 
 // With a complex hypermatrix
-x = matrix(1:12, [2, 3, 2])*%i;
+x = x0*%i;
 y = permute(x, [3 1 2]);
-clear refY
-refY(:, :, 1) = [1 2; 7 8]*%i;
-refY(:, :, 2) = [3 4; 9 10]*%i;
-refY(:, :, 3) = [5 6; 11 12]*%i;
+refY = refY0*%i;
+assert_checkequal(y, refY);
 
+// With an hypermatrix of polynomials
+x = 1 + x0*%z;
+y = permute(x, [3 1 2]);
+refY = 1 + refY0*%z;
 assert_checkequal(y, refY);
 
+// With an hypermatrix of rationals
+x = (1 + x0*%z)./(1 - x0*%z);
+y = permute(x, [3 1 2]);
+refY = (1 + refY0*%z) ./ (1 - refY0*%z);
+assert_checkequal(y, refY);
+
+// With an array of structures
+s(3,4,2).r = %pi;
+ss = size(s);
+ps = permute(s,[2 3 1]);
+assert_checkequal(size(ps),ss([2 3 1]));
+assert_checkequal(ps(24).r, %pi);
+
+
 // Error checks
-refMsg = msprintf(_("%s: Wrong size for input argument #%d: At least the size of input argument #%d expected.\n"), "permute", 2, 1);
+// ------------
+msg = _("%s: Wrong value for input argument #%d: Must be a valid permutation of [1..n>%d] integers.\n");
+refMsg = msprintf(msg, "permute", 2, 2);
 assert_checkerror("permute(x, [1 2]);", refMsg);
-refMsg = msprintf(_("%s: Wrong value for input argument #%d: Must be a valid permutation vector.\n"), "permute", 2);
 assert_checkerror("permute(x, [1 2 4]);", refMsg);
+assert_checkerror("permute(x, [1 3.1 2]);", refMsg);
 assert_checkerror("permute(x, [1 2 3 5]);", refMsg);