<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2019 - 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="perms" xml:lang="fr">
    <refnamediv>
        <refname>perms</refname>
        <refpurpose>Génère le tableau des permutations des éléments donnés</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>
            y = perms(x)
            y = perms(x, "unique")
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>
                        Vecteur ligne ou colonne de tout type de données pour lesquelles les
                        opérateurs size(), ==, et [] sont définis, incluant le type cell.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"unique"</term>
                <listitem>
                    <para>
                        indicateur texte optionnel, pour calculer et produire uniquement les
                        permutations uniques, sans aucun doublon.
                        Cette option est utilisable uniquement si <varname>x</varname> est ordonnable :
                        booléen, entier, réel, ou texte.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                        Tableau du type de x, avec n=size(x,"*") colonnes.
                        Chaque ligne contient une permutation. Sans utiliser l'option "unique",
                        <varname>y</varname> comprend n! lignes. Sinon, le nombre de lignes
                        size(y,1) ≤ n! dépend de la multiplicité des valeurs dédoublonnées de x.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Etant donné un vecteur <literal>x</literal> de <literal>n</literal> éléments,
            <literal>perms(..)</literal> calcule le nombre attendu de permutations attendues,
            et vérifie qu'il y a suffisamment de mémoire vive disponible pour les calculer et les
            stocker en résultat.
        </para>
        <para>
            S'il n'y a pas suffisamment de mémoire vive, aucun calcul effectif n'est effectué,
            et une erreur est générée.
        </para>
        <para>
            Sinon, les permutations sont calculées et retournées en résultat.
        </para>
        <note>
            Lorsque "unique" est utilisé,
            <itemizedlist>
                <listitem>
                    si aucun doublon n'est détecté dans <varname>x</varname>,
                    l'algorithme sans "unique" est automatiquement utilisé pour effectuer
                    les calculs plus rapidement.
                </listitem>
                <listitem>
                    <varname>x</varname> est préalablement trié en ordre croissant, et
                    <varname>y</varname> est construite en ordre lexicographique croissant.
                </listitem>
            </itemizedlist>
            Sinon : l'ordre initial des éléments de <varname>x</varname> est conservé, et l'ordre
            des permutations dans <varname>y</varname> en tient compte. Ainsi <varname>x</varname>
            pourra si besoin être trié selon l'ordre <emphasis>choisi par l'utilisateur,
            avant</emphasis> d'appeler <literal>perms()</literal>.
        </note>
        <warning>
            Pour mémoire, le poids <varname>n*n!*8</varname> de <varname>y</varname> en octets
            est listé ci-dessous en fonction du nombre <literal>n</literal> d'éléments de
            <varname>x</varname>, pour <varname>x</varname> nombres décimaux, et sans
            l'option "unique" :
        </warning>
        <para>
            <table border="1">
                <tr align="center">
                    <th>n</th>
                    <td>2</td><td>3</td><td>4</td><td>5</td><td>6</td><td>7</td><td>8</td>
                    <td>9</td><td>10</td><td>11</td><td>12</td><td>13</td>
                </tr>
                <tr>
                    <th>y [octets]</th>
                    <td>32</td><td>144</td><td>768</td><td>4800</td><td>34560</td><td>288240</td>
                    <td>2.58×10<superscript>6</superscript></td>
                    <td>26.1×10<superscript>6</superscript></td>
                    <td>290×10<superscript>6</superscript></td>
                    <td>3.51×10<superscript>9</superscript></td>
                    <td>46.0×10<superscript>9</superscript></td>
                    <td>648×10<superscript>9</superscript></td>
                </tr>
            </table>
        </para>
    </refsection>
    <refsection>
        <title>Exemples</title>
        <programlisting role="example"><![CDATA[
x = [4, 7, 10];
y = perms(x)

x = ["a" "b" "c" "d"];
y = perms(x)'

c = {"bonjour", %pi, %t};
perms(c)
 ]]></programlisting>
    <screen><![CDATA[
--> x = [4, 7, 10];
--> y = perms(x)
 y  =
   10.   7.    4.
   10.   4.    7.
   7.    10.   4.
   7.    4.    10.
   4.    10.   7.
   4.    7.    10.

--> x = ["a" "b" "c" "d"];
--> perms(x)'
 ans  =
!d  d  d  d  d  d  c  c  c  c  c  c  b  b  b  b  b  b  a  a  a  a  a  a  !
!c  c  b  b  a  a  d  d  b  b  a  a  d  d  c  c  a  a  d  d  c  c  b  b  !
!b  a  c  a  c  b  b  a  d  a  d  b  c  a  d  a  d  c  c  b  d  b  d  c  !
!a  b  a  c  b  c  a  b  a  d  b  d  a  c  a  d  c  d  b  c  b  d  c  d  !

--> c = {"bonjour", %pi, %t};
--> perms(c)
 ans  =
  [1x1 boolean ]  [1x1 constant]  [1x1 string  ]
  [1x1 boolean ]  [1x1 string  ]  [1x1 constant]
  [1x1 constant]  [1x1 boolean ]  [1x1 string  ]
  [1x1 constant]  [1x1 string  ]  [1x1 boolean ]
  [1x1 string  ]  [1x1 boolean ]  [1x1 constant]
  [1x1 string  ]  [1x1 constant]  [1x1 boolean ]
]]></screen>
    <para>
        Avec des éléments de multiplicité > 1 (doublons ou plus) :
    </para>
    <programlisting role="example"><![CDATA[
perms([1 0 0])
perms([1 0 0], "unique")
perms([0 1 2 0], "unique")'
p = perms([0 0 0 0 1 1 1 2 2 3], "unique");
size(p)
 ]]></programlisting>
    <screen><![CDATA[
--> perms([1 0 0])
 ans  =
   0.   0.   1.
   0.   1.   0.
   0.   0.   1.
   0.   1.   0.
   1.   0.   0.
   1.   0.   0.

--> perms([1 0 0], "unique")
 ans  =
   0.   0.   1.
   0.   1.   0.
   1.   0.   0.

--> perms([0 1 2 0], "unique")'
 ans  =
   0.   0.   0.   0.   0.   0.   1.   1.   1.   2.   2.   2.
   0.   0.   1.   1.   2.   2.   0.   0.   2.   0.   0.   1.
   1.   2.   0.   2.   0.   1.   0.   2.   0.   0.   1.   0.
   2.   1.   2.   0.   1.   0.   2.   0.   0.   1.   0.   0.

--> p = perms([0 0 0 0 1 1 1 2 2 3], "unique");
--> size(p)
 ans  =
   12600.   10.  // au lieu de 10! = 3628800 lignes
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <link linkend="grand">grand(n,'prm',x)</link>
            </member>
            <member>
                <link linkend="factorial">factorial</link>
            </member>
            <member>
                <link linkend="unique">unique</link>
            </member>
            <member>
                <link linkend="gsort">gsort</link>
            </member>
            <member>
                <link linkend="try">try</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>Historique</title>
        <revhistory>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    Option "unique" ajoutée.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
