<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA - Jean-Baptiste SILVY
 * Copyright (C) 2013, 2016, 2017 - 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="resize_matrix" xml:lang="fr">
    <refnamediv>
        <refname>resize_matrix</refname>
        <refpurpose>élague et/ou étend (et convertit) une matrice ou une hypermatrice</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntaxe</title>
        <synopsis>
                     resize_matrix    //  Démo
            resMat = resize_matrix(mat, nbRows, nbCols)

            resMat = resize_matrix(mat, nbRows, nbCols, resType)
            resMat = resize_matrix(mat, nbRows, nbCols, resType, padding)
            resMat = resize_matrix(mat, nbRows, nbCols,    ""  , padding)

            resMat = resize_matrix(mat, newSizes)
            resMat = resize_matrix(mat, newSizes, resType)
            resMat = resize_matrix(mat, newSizes, resType, padding)
            resMat = resize_matrix(mat, newSizes,    ""  , padding)
        </synopsis>
    </refsynopsisdiv>
    <refsection role="parameters">
        <title>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>mat</term>
                <listitem>
                    <para>Matrice à retailler, de type booléens, entiers encodés, décimaux (réels
                    ou complexes), polynômes, ou texte
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nbRows</term>
                <listitem>
                    <para>nouveau nombre de lignes de la matrice retaillée. Les lignes en trop sont
                      supprimées. Les lignes manquantes sont créées.
                     Spécifier <literal>nbRows &lt; 0</literal> pour conserver le nombre de
                      lignes courant.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nbCols</term>
                <listitem>
                    <para>nouveau nombre de colonnes de la matrice retaillée. Les colonnes en trop
                      sont supprimées. Les colonnes manquantes sont créées.
                     Spécifier <literal>nbCols &lt; 0</literal> pour conserver le nombre de
                      colonnes courant.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>newSizes</term>
                <listitem>
                    <para>
                        vecteur spécifiant les nouvelles tailles de <literal>mat</literal> selon
                        ses différentes dimensions.
                        Pour conserver une taille à la taille actuelle, indiquer -1.
                    </para>
                    <para>
                        S'il est plus court que <literal>size(mat)</literal>, il est complété avec
                        des 1. Exemple: si <varname>mat</varname> telle que
                        <literal>size(mat)==[ 4 3 3 2]</literal> est fournie, et
                        <literal>newSizes=[6 2]</literal> est spécifié,
                        <literal>newSizes = [6 2 1 1]</literal> sera utilisé.
                    </para>
                    <para>
                        Si <varname>newSizes</varname> est plus long que <literal>size(mat)</literal>
                        avec <literal>newSizes($)>1</literal>, une ou plusieurs dimensions sont
                        ajoutées à <varname>mat</varname>. Exemple: si <varname>mat</varname> telle
                        que <literal>size(mat)==[ 4 3 ]</literal> est fournie avec
                        <literal>newSizes=[6 2 2]</literal>, le résultat sera une hypermatrice de
                        2 pages, la seconde étant complètement initialisée.
                    </para>
                    <para>
                        <literal>newSizes = [nbRows, nbCols]</literal> peut être utilisé pour une matrice.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>resType</term>
                <listitem>
                    <para>
                    option indiquant le type en lequel la matrice/hypermatrice retaillée doit
                    être convertie. resType peut être "boolean", "constant", "string", "int8",
                    "uint8", "int16", "uint16", "int32", "uint32", "int64", ou "uint64".
                    </para>
                    <para>
                        Aucune conversion n'est admise pour une matrice ou hypermatrice de polynômes,
                        ni pour une hypermatrice de texte.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>padding</term>
                <listitem>
                    <para>
                        option de même type que <varname>mat</varname>, spécifiant le contenu
                        scalaire à affecter aux éléments ajoutés à <varname>mat</varname> lorsque sa
                        taille selon une dimension est augmentée. La valeur utilisée par défaut est
                        <literal>0</literal> (réels, complexes, entiers encodés, polynômes),
                        ou <literal>""</literal> (texte), ou <literal>%F</literal> (booléens).
                    </para>
                    <para>
                        Lorsque les types de <varname>mat</varname> et <varname>padding</varname>
                        sont distincts, Scilab tente de convertir le type de <varname>padding</varname>.
                    </para>
                    <para>
                        Pour les polynômes, le nom de l'inconnue du polynôme <varname>padding</varname>
                        est forcé à celui de <varname>mat</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>resMat</term>
                <listitem>
                    <para>matrice ou hypermatrice retaillée (et convertie)</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Description</title>
        <para>
            Crée une matrice de taille <literal>[nbRows, nbCols]</literal> ou
            <literal>newSizes</literal>, ou une hypermatrice de taille <literal>newSizes</literal>.
            Si, pour une certaine dimension, la nouvelle taille est plus petite que l'initiale, la
            matrice est élaguée. Si la taille est agrandie, alors de nouveaux éléments valant
            <literal>padding</literal> sont ajoutés à la matrice/hypermatrice.
            Le nombre de dimensions peut être augmenté.
        </para>
        <para>
            Le type du résultat peut être modifié en spécifiant l'argument <literal>resType</literal>,
            avec les restrictions mentionnées ci-dessus.
        </para>
    </refsection>
    <refsection role="examples">
        <title>Exemples</title>
        <programlisting role="example"><![CDATA[
// Exemples de démonstration, dont avec des polynômes :
resize_matrix

// Retaillage d'une matrice numérique
M = grand(4, 3, "uin", -9, 9)
resize_matrix(M, -1, 5)  //  Indiquer -1 pour conserver la taille courante
resize_matrix(M, 2, -1)
resize_matrix(M, 3, 4)
 ]]></programlisting>
    <screen><![CDATA[--> M = grand(4, 3, "uin", -9, 9)
 M  =
  -8.  -5.  -2.
  -9.   0.  -1.
   4.  -1.   6.
   5.   1.   8.

--> resize_matrix(M, -1, 5)  //  Indiquer -1 pour conserver la taille courante
 ans  =
  -8.  -5.  -2.   0.   0.
  -9.   0.  -1.   0.   0.
   4.  -1.   6.   0.   0.
   5.   1.   8.   0.   0.

--> resize_matrix(M, 2, -1)
 ans  =
  -8.  -5.  -2.
  -9.   0.  -1.

--> resize_matrix(M, 3, 4)
 ans  =
  -8.  -5.  -2.   0.
  -9.   0.  -1.   0.
   4.  -1.   6.   0.
]]></screen>
        <programlisting role="example"><![CDATA[
resize_matrix(M, [3 4 2])
resize_matrix(M, [3 4 2], "", %i)
resize_matrix(M, [3 4 2], "string", %i)

// Matrice de texte
myMatString = ["Scilab", "the" ; "Open Source", "Scientific" ; "Software", "Package"]
resize_matrix( myMatString, 5, 3 )
// Equivalent syntax for new sizes:
resize_matrix( myMatString, [5 3], "", "$" ) // Contenu d'extension à façon

// Elagage, extension et conversion d'une hypermatrice donnée
h = rand(2, 3, 2)*200
resize_matrix(h, [3 2 3], "int8")
resize_matrix(h, [3 2 3], "int8", -1)   // Extension avec des -1 et conversion en int8
r = resize_matrix(h, [3 2 ] ,"" , -1)   // Extension à façon, sans conversion
size(r)  // La dernière dimension réduite à un singleton a automatiquement été simplifiée

// Matrice de polynômes
x = poly(0, "x");
P = (1-x)^grand(4, 2, "uin", 0, 3)
resize_matrix(P, 3, 3)
resize_matrix(P, [3 3 2])
resize_matrix(P, [3 3 2], "", %z)
//  => L'inconnue de %z est forcée à celle de P => x
//  => La matrice de polynômes résultante n'est pas convertible
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <link linkend="matrix">matrix</link>
            </member>
            <member>
                <link linkend="size">size</link>
            </member>
            <member>
                <link linkend="typeof">typeof</link>
            </member>
            <member>
                <link linkend="double">double</link>
            </member>
            <member>
                <link linkend="strtod">strtod</link>
            </member>
            <member>
                <link linkend="string">string</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>Historique</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            Les polynômes et les hypermatrices sont désormais acceptés.
                        </listitem>
                        <listitem>
                            La valeur affectée aux éléments d'extension peut être spécifiée.
                        </listitem>
                        <listitem>
                            Les nouvelles tailles peuvent être spécifiées dans un vecteur.
                        </listitem>
                        <listitem>
                            resize_matrix() appelée sans paramètres affiche des exemples de démonstration.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0.1</revnumber>
                <revremark>
                    L'option <literal>resType</literal> est étendue aux nouveaux types entiers
                    <literal>int64</literal> et <literal>uint64</literal>.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
