<?xml version="1.0" encoding="UTF-8"?>
<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="extraction" xml:lang="fr">
    <refnamediv>
        <refname>extraction</refname>
        <refpurpose>extraction à partir d'une matrice ou d'une liste</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>
            x(i)
            x(i,j)
            x(i,j,k,...)
            [...] = l(i)
            [...] = l(k1)...(kn)(i) ou [...] = l(list(k1,...,kn,i))
            l(k1)...(kn)(i,j) ou l(list(k1,...,kn,list(i,j))
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>x </term>
                <listitem>
                    <para>matrice de tout type</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>l</term>
                <listitem>
                    <para>liste</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>i,j, k, ..</term>
                <listitem>
                    <para>indices</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>k1,...kn</term>
                <listitem>
                    <para>indices à valeurs entières</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <refsect3>
            <title>Cas des matrices</title>
            <para>
              <literal>i</literal>, <literal>j</literal>,
              <literal>k</literal>, ... peuvent être :
            </para>
            <variablelist>
              <varlistentry>
                <term>Un scalaire, un vecteur ou une matrice à éléments
                  positifs.
                </term>
                <listitem>
                  <itemizedlist>
                    <listitem>
                      <para>
                        <literal>r=x(i,j)</literal> construit la matrice
                        <literal>r</literal> telle que:
                      </para>
                      <para>
                        <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal>
                      </para>
                      <para>
                        pour <literal>l</literal> variant de 1 à
                        <literal>size(i,'*')</literal>
                      </para>
                      <para>
                        et <literal>k</literal> variant de 1 à
                        <literal>size(j,'*')</literal>.
                      </para>
                      <para>
                        La valeur maximale de <literal>i</literal> (resp.
                        <literal>j</literal>) doit être inférieure ou égale à
                        <literal>size(x,1)</literal> (resp.
                        <literal>size(x,2)</literal>).
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        <literal>r=x(i)</literal> où <literal>x</literal>
                        est une matrice 1 x 1, construit la matrice
                        <literal>r</literal> telle que
                        <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> pour
                        <literal>l</literal> variant de 1 à
                        <literal>size(i,1)</literal> et <literal>k</literal>
                        variant de 1 à <literal>size(i,2)</literal>. Noter que
                        dans ce cas l'indice <literal>i</literal> est valable si
                        toutes ses composantes sont égales à 1.
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        <literal>r=x(i)</literal> avec <literal>x</literal>
                        un vecteur ligne, construit le vecteur ligne
                        <literal>r</literal> tel que
                        <literal>r(l)=x(int(i(l)))</literal> pour
                        <literal>l</literal> entre 1 et
                        <literal>size(i,'*')</literal> La valeur maximale de
                        <literal>i</literal> doit être inférieure ou égale à
                        <literal>size(x,'*')</literal>.
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        <literal>r=x(i)</literal> avec <literal>x</literal>
                        une matrice à une ou plusieurs colonnes, construit la
                        matrice <literal>r</literal> telle que
                        <literal>r(l)</literal> (<literal>l</literal> variant de 1
                        à <literal>size(i,'*')</literal>) contient le terme numéro
                        <literal>int(i(l))</literal> du vecteur colonne issu de la
                        concaténation des colonnes de <literal>x</literal>. La
                        valeur maximale de <literal>i</literal> doit être
                        inférieure ou égale à
                        <literal>size(x,'*')</literal>.
                      </para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>Le symbole</term>
                <listitem>
                  <para>
                    <literal> : </literal> signifiant "tous les
                    éléments".
                  </para>
                  <itemizedlist>
                    <listitem>
                      <para>
                        <literal>r=x(i,:)</literal> construit la matrice
                        <literal>r</literal> telle que
                        <literal>r(l,k)=x(int(i(l)),k))</literal> pour
                        <literal>l</literal> variant de 1 à
                        <literal>size(i,'*')</literal> et <literal>k</literal>
                        variant de 1 à <literal>size(x,2)</literal>
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        <literal>r=x(:,j)</literal> construit la matrice
                        <literal>r</literal> telle que
                        <literal>r(l,k)=x(l,int(j(k)))</literal> pour
                        <literal>l</literal> variant de 1 à
                        <literal>size(r,1)</literal> et <literal>k</literal>
                        variant de 1 à <literal>size(j,'*')</literal>.
                      </para>
                    </listitem>
                    <listitem>
                      <para>
                        <literal>r=x(:)</literal> construit le vecteur
                        colonne <literal>r</literal> obtenu par concaténation des
                        colonnes de <literal> x</literal>. Cette commande est
                        équivalente à
                        <literal>r=matrix(x,size(x,'*'),1)</literal>.
                      </para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>Un vecteur de booléens</term>
                <listitem>
                  <para>
                    Si un indice (<literal>i</literal> ou
                    <literal>j</literal> ) est un vecteur de booléen il est
                    interprété comme <literal>find(i)</literal> ou
                    <literal>find(j)</literal>, respectivement.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>Un polynôme</term>
                <listitem>
                  <para>
                    Si un indice (<literal>i</literal> ou
                    <literal>j</literal> ) est un vecteur de polynômes ou de
                    polynômes implicites il est interprété comme
                    <literal>horner(i,m)</literal> ou
                    <literal>horner(j,n)</literal>, respectivement, où
                    <literal>m</literal> et <literal>n</literal> sont les
                    dimensions de <literal>x</literal> associées. Même si cette
                    fonctionnalité marche pour tous les polynômes, il est
                    recommandé d'utiliser des polynômes dans <literal>$</literal>
                    par souci de lisibilité.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
            <para>Dans le case des matrices ayant plus de 2 dimensions
              (voir:<link linkend="hypermatrices">hypermatrices</link>) la
              dimensionalité est automatiquement réduite si les dimensions les
              plus à droite sont égales à 1.
            </para>
        </refsect3>
        <refsect3>
            <title>Cas des listes</title>
            <para>
              S'ils sont présents, les <literal>ki</literal> donnent le
              chemin vers un terme d'une sous-liste de la liste
              <literal>l</literal>. Ils permettent de faire une extraction
              récursive directe sans utiliser de variable intermédiaire.
            </para>
            <para> Les instructions:</para>
            <para>
              <literal>[...]=l(k1)...(kn)(i) et
                [...]=l(list(k1,...,kn,i))
              </literal>
            </para>
            <para>sont interprétées comme :</para>
            <para>
              <literal>lk1 = l(k1)</literal>, <literal> .. = .. </literal>,
              <literal>lkn = lkn-1(kn)</literal>, <literal>[...] =
              lkn(i)
              </literal>
            </para>
            <para>De même, les instructions</para>
            <para>
              <literal>l(k1)...(kn)(i,j) et
                l(list(k1,...,kn,list(i,j))
              </literal>
            </para>
            <para>sont interprétées comme :</para>
            <para>
              <literal>lk1 = l(k1)</literal>, <literal> .. = .. </literal>,
              <literal>lkn = lkn-1(kn)</literal>,
              <literal>lkn(i,j)</literal>
            </para>
            <variablelist>
              <varlistentry>
                <term>
                  <literal>i</literal> et <literal>j</literal>, peuvent être
                  :
                </term>
                <listitem>
                  <variablelist>
                    <varlistentry>
                      <term>un scalaire, un vecteur ou matrice à termes positifs </term>
                      <listitem>
                        <para>
                          <literal>[r1,...rn]=l(i)</literal> extrait les termes
                          <literal>i(k)</literal> de la liste l et les stocke dans les
                          variables <literal>rk</literal> pour <literal>k</literal>
                          variant de 1 à <literal>size(i,'*')</literal>
                        </para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>
                        le symbole <literal> : </literal>
                      </term>
                      <listitem>
                        <para> qui représente "tous les éléments".</para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>un vecteur de booléens</term>
                      <listitem>
                        <para>
                          Si <literal>i</literal> est un vecteur de booléens, il
                          est interprété comme <literal>find(i)</literal>.
                        </para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>un polynôme</term>
                      <listitem>
                        <para>
                          Si <literal>i</literal> est un vecteur de polynômes ou
                          de polynômes implicites il est interprété comme
                          <literal>horner(i,m)</literal> où
                          <literal>m=size(l)</literal>. Même si cette fonctionnalité
                          marche pour tous les polynômes, il est recommandé d'utiliser
                          des polynômes dans <literal>$</literal> par souci de
                          lisibilité.
                        </para>
                      </listitem>
                    </varlistentry>
                  </variablelist>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <literal>k1</literal>,..<literal>kn</literal> peuvent être :
                </term>
                <listitem>
                  <variablelist>
                    <varlistentry>
                      <term>un nombre réel positif à valeur entière</term>
                      <listitem>
                        <para/>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>un polynôme</term>
                      <listitem>
                        <para>un polynôme, interprété comme
                          <literal>horner(ki,m)</literal> ou <literal>m</literal> est la
                          taille de la sous-liste correspondante.
                        </para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>une chaîne de caractères</term>
                      <listitem>
                        <para>associée à un nom d'entrée de sous-liste</para>
                      </listitem>
                    </varlistentry>
                  </variablelist>
                </listitem>
              </varlistentry>
            </variablelist>
            <para>Quand le chemin désigne plusieurs termes d'une liste
              l'instruction doit avoir autant de termes dans la liste des
              arguments du membre de gauche que le nombre de termes sélectionnés.
              Mais si la syntaxe d'extraction est utilisée dans les arguments
              d'entrée d'une fonction, chaque terme renvoyé est ajouté aux
              arguments d'entrée.
            </para>
            <para>
              Notez que <literal>l(list())</literal> est identique à
              <literal>l</literal>.
            </para>
        </refsect3>
        <refsect3>
            <title>Remarques</title>
            <para>Pour les matrices rationnelles et les systèmes dynamiques linéaires
                stockés sous forme de représentation d'état, la syntaxe
                <literal>x(i)</literal> ne doit pas être utilisée pour l'extraction des
                éléments d'un vecteur, à cause de la confusion possible avec l'extraction
                des éléments de liste. La syntaxe <literal>x(1,j)</literal> où
                <literal>x(i,1)</literal> doit être utilisée dans ce cas.
            </para>
        </refsect3>
    </refsection>
    <refsection>
        <title>Exemples</title>
        <para>
            Cas des matrices :
        </para>
        <programlisting role="example"><![CDATA[
a = [1 2 3;4 5 6]
a(1,2)
a([1 1],2)
a(:,1)
a(:, 3:-1:1)
a(1)
a(6)
a(:)
a([%t %f %f %t])
a([%t %f], [2 3])
a(1:2, $-1)
a($:-1:1,2)
a($)
//
x = 'test'
x([1 1;1 1;1 1])
//
b = [1/%s, (%s+1)/(%s-1)]
b(1,1)
b(1,$)
b(2) // le numérateur
     ]]></programlisting>
        <para>
            Cas des listes simples et des listes typées tlist :
        </para>
        <programlisting role="example"><![CDATA[
l = list(1,'qwerw',%s)
l(1)
[a,b] = l([3 2])
l($)
x = tlist(l(2:3))  // construction d'une TLIST avec les deux derniers termes de l
//
dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
dts(2)('a')
dts(2)('b')(1,2)
[a,b] = dts(2)(['a','b'])
     ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Voir aussi</title>
        <simplelist type="inline">
            <member>
                <link linkend="insertion">insertion</link>
            </member>
            <member>
                <link linkend="colon">colon</link>
            </member>
            <member>
                <link linkend="find">find</link>
            </member>
            <member>
                <link linkend="horner">horner</link>
            </member>
            <member>
                <link linkend="parentheses">parentheses</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
