<?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>
        <refsect3>
            <title>Matrix case</title>
            <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>
        </refsect3>
        <refsect3>
            <title>List or Tlist case</title>
            <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>
        </refsect3>
        <refsect3>
            <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>
        </refsect3>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            Matrix case:
        </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) // the numerator
     ]]></programlisting>
        <para>
            List ot Tlist case:
        </para>
        <programlisting role="example"><![CDATA[
l = list(1,'qwerw',%s)
l(1)
[a,b] = l([3 2])
l($)
x = tlist(l(2:3)) // forms 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="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>
