<?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>
        <variablelist>
            <varlistentry>
                <term>CAS DES MATRICES</term>
                <listitem>
                    <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>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>CAS DES LISTES</term>
                <listitem>
                    <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>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <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>
    </refsection>
    <refsection>
        <title>Exemples</title>
        <programlisting role="example"><![CDATA[
// CAS DES MATRICES
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
// CAS des LISTES (types LIST et TLIST)
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="find">find</link>
            </member>
            <member>
                <link linkend="horner">horner</link>
            </member>
            <member>
                <link linkend="parentheses">parentheses</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
