<?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="en">
    <refnamediv>
        <refname>extraction</refname>
        <refpurpose>matrix and list entry extraction</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            x(i)
            x(i,j)
            x(i,j,k,..)
            [...]=l(i)
            [...]=l(k1)...(kn)(i) or [...]=l(list(k1,...,kn,i))
            l(k1)...(kn)(i,j) or l(list(k1,...,kn,list(i,j))
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>matrix of any possible types</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>l</term>
                <listitem>
                    <para>list variable</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>i,j, k</term>
                <listitem>
                    <para>indices</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>k1,...kn</term>
                <listitem>
                    <para>indices</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <variablelist>
            <varlistentry>
                <term>MATRIX CASE</term>
                <listitem>
                    <para>
                        <literal>i</literal>, <literal>j</literal>,
                        <literal>k</literal>,.. can be:
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>a real scalar or a vector or a matrix with positive
                                elements.
                            </term>
                            <listitem>
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <literal>r=x(i,j)</literal> builds the matrix
                                            <literal>r</literal> such as
                                            <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal> for
                                            <literal>l</literal> from 1 to
                                            <literal>size(i,'*')</literal> and <literal>k</literal>
                                            from 1 to <literal>size(j,'*')</literal>.
                                        </para>
                                        <para>
                                            <literal>i</literal> (<literal>j</literal>) Maximum
                                            value must be less or equal to
                                            <literal>size(x,1)</literal>
                                            (<literal>size(x,2)</literal>).
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>r=x(i)</literal> with <literal>x</literal>
                                            a 1x1 matrix builds the matrix <literal>r</literal> such
                                            as <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> for
                                            <literal>l</literal> from 1 to
                                            <literal>size(i,1)</literal> and <literal>k</literal> from
                                            1 to <literal>size(i,2)</literal>.
                                        </para>
                                        <para>
                                            Note that in this case index <literal>i</literal> is
                                            valid only if all its entries are equal to one.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>r=x(i)</literal> with <literal>x</literal>
                                            a row vector builds the row vector <literal>r</literal>
                                            such as <literal>r(l)=x(int(i(l)))</literal> for
                                            <literal>l</literal> from 1 to
                                            <literal>size(i,'*')</literal><literal>i</literal> Maximum
                                            value must be less or equal to
                                            <literal>size(x,'*')</literal>.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>r=x(i)</literal> with <literal>x</literal>
                                            a matrix with one or more columns builds the column vector
                                            <literal>r</literal> such as <literal>r(l)</literal>
                                            (<literal>l</literal> from 1 to
                                            <literal>size(i,'*')</literal>) contains the
                                            <literal>int(i(l))</literal> entry of the column vector
                                            formed by the concatenation of the <literal>x</literal>'s
                                            columns.
                                        </para>
                                        <para>
                                            <literal>i</literal> Maximum value must be less or
                                            equal to <literal>size(x,'*')</literal>.
                                        </para>
                                    </listitem>
                                </itemizedlist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>
                                the symbol <literal>: </literal>
                            </term>
                            <listitem>
                                <para><literal/>
                                    which stands for "all elements".
                                </para>
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <literal>r=x(i,:)</literal> builds the matrix
                                            <literal>r</literal> such as
                                            <literal>r(l,k)=x(int(i(l)),k))</literal> for
                                            <literal>l</literal> from 1 to
                                            <literal>size(i,'*')</literal> and <literal>k</literal>
                                            from 1 to <literal>size(x,2)</literal>
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>r=x(:,j)</literal> builds the matrix
                                            <literal>r</literal> such as
                                            <literal>r(l,k)=x(l,int(j(k)))</literal> for
                                            <literal>l</literal> from 1 to
                                            <literal>size(r,1)</literal> and <literal>k</literal> from
                                            1 to <literal>size(j,'*')</literal>.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>r=x(:)</literal> builds the column vector
                                            <literal>r</literal> formed by the column concatenations
                                            of <literal>x</literal> columns. It is equivalent to
                                            <literal>matrix(x,size(x,'*'),1)</literal>.
                                        </para>
                                    </listitem>
                                </itemizedlist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>a vector of boolean</term>
                            <listitem>
                                <para>
                                    If an index (<literal>i</literal> or
                                    <literal>j</literal>) is a vector of booleans it is
                                    interpreted as <literal>find(i)</literal> or respectively
                                    <literal>find(j)</literal>
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>a polynomial</term>
                            <listitem>
                                <para>
                                    If an index (<literal>i</literal> or
                                    <literal>j</literal>) is a vector of polynomials or implicit
                                    polynomial vector it is interpreted as
                                    <literal>horner(i,m)</literal> or respectively
                                    <literal>horner(j,n)</literal> where <literal>m</literal> and
                                    <literal>n</literal> are associated <literal>x</literal>
                                    dimensions. Even if this feature works for all polynomials, it
                                    is recommended to use polynomials in <literal>$</literal> for
                                    readability.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                    <para>
                        For matrices with more than 2 dimensions (see:<link linkend="hypermatrices">hypermatrices</link>) the dimensionality
                        is automatically reduced when right-most dimensions are equal to
                        1.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>LIST OR TLIST CASE</term>
                <listitem>
                    <para>
                        If they are present the <literal>ki</literal> give the path to
                        a sub-list entry of <literal>l</literal> data structure. They allow
                        a recursive extraction without intermediate copies. The
                        instructions
                    </para>
                    <para>
                        <literal>[...]=l(k1)...(kn)(i)</literal>
                    </para>
                    <para>and</para>
                    <para>
                        <literal>[...]=l(list(k1,...,kn,i))</literal>
                    </para>
                    <para>are interpreted as:</para>
                    <para>
                        <literal>lk1 = l(k1)</literal>
                    </para>
                    <para>
                        <literal>.. = .. </literal>
                    </para>
                    <para>
                        <literal>lkn = lkn-1(kn)</literal>
                    </para>
                    <para>
                        <literal>[...] = lkn(i)</literal>.
                    </para>
                    <para>
                        And the <literal>l(k1)...(kn)(i,j)</literal> and
                    </para>
                    <para>
                        <literal>l(list(k1,...,kn,list(i,j))</literal> instructions
                        are interpreted as:
                    </para>
                    <para>
                        <literal>lk1 = l(k1)</literal>
                    </para>
                    <para>
                        <literal>.. = .. </literal>
                    </para>
                    <para>
                        <literal>lkn = lkn-1(kn)</literal>
                    </para>
                    <para>
                        <literal>
                            lkn(i,j)
                        </literal>
                    </para>
                    <para>
                        When path points to more than one list component, the
                        instruction must have as many left-hand side arguments as selected
                        components. But if the extraction syntax is used as function
                        parameters, each returned list component is added to the
                        function parameters.
                    </para>
                    <para>
                        Note that <literal>l(list())</literal> is the same as
                        <literal>l</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>i and j may be:</term>
                            <listitem>
                                <variablelist>
                                    <varlistentry>
                                        <term>real scalar or vector or matrix with positive
                                            elements.
                                        </term>
                                        <listitem>
                                            <para>
                                                <literal>[r1,...rn]=l(i)</literal> extracts the
                                                <literal>i(k)</literal> elements from the list <literal>l</literal> and store
                                                them in <literal>rk</literal> variables for
                                                <literal>k</literal> from 1 to
                                                <literal>size(i,'*')</literal>
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>
                                            the symbol <literal>: </literal>
                                        </term>
                                        <listitem>
                                            <para>which stands for "all elements".</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>a vector of booleans.</term>
                                        <listitem>
                                            <para>
                                                If <literal>i</literal> is a vector of booleans it is
                                                interpreted as <literal>find(i)</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>a polynomial</term>
                                        <listitem>
                                            <para>
                                                If <literal>i</literal> is a vector of polynomials or
                                                implicit polynomial vector it is interpreted as
                                                <literal>horner(i,m)</literal> where
                                                <literal>m=size(l)</literal>. Even if this feature works for
                                                all polynomials, it is recommended to use polynomials in
                                                <literal>$</literal> for readability.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>k1 ... kn may be :</term>
                            <listitem>
                                <variablelist>
                                    <varlistentry>
                                        <term>real positive scalar</term>
                                        <listitem>
                                            <para/>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>a polynomial</term>
                                        <listitem>
                                            <para>
                                                interpreted as <literal>horner(ki,m)</literal> where
                                                <literal>m</literal> is the corresponding sub-list
                                                size.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>a character string</term>
                                        <listitem>
                                            <para>associated with a sub-list entry name.</para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Remarks</title>
        <para>For soft coded matrix types such as rational functions and state
            space linear systems, <literal>x(i)</literal> syntax may not be used for
            vector element extraction due to confusion with list element extraction.
            <literal>x(1,j)</literal> or <literal>x(i,1)</literal> syntax must be
            used.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// MATRIX CASE
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) // the numerator
// LIST OR TLIST CASE
l=list(1,'qwerw',%s)
l(1)
[a,b]=l([3 2])
l($)
x=tlist(l(2:3)) //form a tlist with the last 2 components of 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>See also</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>
            <member>
                <link linkend="insertion">insertion</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
