scilab/modules/data_structures/help/en_US/list.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) 2006-2008 - INRIA
   5  *
   6  * This file must be used under the terms of the CeCILL.
   7  * This source file is licensed as described in the file COPYING, which
   8  * you should have received as part of this distribution.  The terms
   9  * are also available at
  10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  11  *
  12  -->
  13 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="list">
  14     <refnamediv>
  15         <refname>list</refname>
  16         <refpurpose>a Scilab object and a list definition function</refpurpose>
  17     </refnamediv>
  18     <refsynopsisdiv>
  19         <title>Calling Sequence</title>
  20         <synopsis>list(a1, ..., an)</synopsis>
  21     </refsynopsisdiv>
  22     <refsection>
  23         <title>Description</title>
  24         <para>
  25             Creates a <literal>list</literal> with elements
  26             <varname>ai</varname>'s which are arbitrary Scilab objects
  27             (<literal>matrix</literal>,
  28             <literal>list</literal>,...). Type of
  29             <literal>list</literal> objects is 15. <code>list()</code>
  30             creates the empty <literal>list</literal> (0 element).
  31         </para>
  32     </refsection>
  33     <refsection>
  34         <title>Operations on lists</title>
  35         <variablelist>
  36             <varlistentry>
  37                 <term>extraction</term>
  38                 <listitem>
  39                     <para>
  40                         <literal>[x,y,z,...]=L(v)</literal> where <literal>v</literal> is a vector of indices;
  41                         <literal>[x,y,z,...]=L(:)</literal> extracts all the elements.
  42                     </para>
  43                 </listitem>
  44             </varlistentry>
  45             <varlistentry>
  46                 <term>insertion at index i</term>
  47                 <listitem>
  48                     <para>
  49                         <code>L(i)=a</code> (note that it is not an
  50                         error to use <code>L(i)=a</code> with
  51                         <code><![CDATA[i > 1 + size(L)]]></code> but
  52                         some list entries are then undefined and their
  53                         extraction gives raise to an error).
  54                     </para>
  55                 </listitem>
  56             </varlistentry>
  57             <varlistentry>
  58                 <term>append an element in queue</term>
  59                 <listitem>
  60                     <para>
  61                         <code>L($+1)=e</code>.
  62                     </para>
  63                 </listitem>
  64             </varlistentry>
  65             <varlistentry>
  66                 <term>append an element in head</term>
  67                 <listitem>
  68                     <para>
  69                         <code>L(0)=e</code>.
  70                         <note>
  71                             After this
  72                             operation <literal>e</literal> is an index 1,
  73                             the initial elements being shifted on the
  74                             right.
  75                         </note>
  76                     </para>
  77                 </listitem>
  78             </varlistentry>
  79             <varlistentry>
  80                 <term>deletion</term>
  81                 <listitem>
  82                     <para>
  83                         <code>L(i)=null()</code> removes the <literal>i</literal>-th element of the list <literal>L</literal>.
  84                     </para>
  85                 </listitem>
  86             </varlistentry>
  87             <varlistentry>
  88                 <term>concatenation of two lists</term>
  89                 <listitem>
  90                     <para>
  91                         <code>L3 = lstcat(L1,L2)</code>.
  92                     </para>
  93                 </listitem>
  94             </varlistentry>
  95             <varlistentry>
  96                 <term>number of elements of a list</term>
  97                 <listitem>
  98                     <para>
  99                         you can use either <code>nb_elm = size(L)</code>
 100                         or <code>nb_elm = length(L)</code>.
 101                     </para>
 102                 </listitem>
 103             </varlistentry>
 104             <varlistentry>
 105                 <term>iterations with a list</term>
 106                 <listitem>
 107                     <para>
 108                         it is possible to use a list <literal>L</literal> with a <link linkend="for">for</link> loop:
 109                         <literal>for e=L,...,end</literal> is a loop with <literal>length(L)</literal>
 110                         iterations, the loop variable <literal>e</literal> being equal to <literal>L(i)</literal>
 111                         at the <literal>i</literal>-th iteration.
 112                     </para>
 113                 </listitem>
 114             </varlistentry>
 115         </variablelist>
 116     </refsection>
 117     <refsection>
 118         <title>Remarks</title>
 119         <para>
 120             Scilab provides also other kinds of list, the <link linkend="tlist">tlist</link> type (typed list) and
 121             the <link linkend="mlist">mlist</link> type which are useful to define a new data type with operator
 122             <link linkend="overloading">overloading</link> facilities (<link linkend="hypermatrices">hypermatrices</link> which are
 123             multidimensional arrays in Scilab are in fact <emphasis>mlist</emphasis>).
 124         </para>
 125         <para>
 126             Matlab <emphasis>struct</emphasis> are also available.
 127         </para>
 128     </refsection>
 129     <refsection>
 130         <title>Examples</title>
 131         <programlisting role="example"><![CDATA[
 132 l = list(1,["a" "b"]) // declaration of a basic list with a double & a vector of two strings
 133 size(l) // Size is 2
 134 // l(0) - Does not exist!
 135 l(1) // Access to the double value
 136 l(2) // Access to the vector of strings
 137 size(l(2)) // Size is 1,2
 138
 139 l(0) = "foo" // Insert at the beginning of the list
 140 // l(0) - still does not exist
 141 l(1) // Is "foo"
 142
 143 l($+1) = "hello" // Insert at the end
 144 l(2) = "toto" // Override my double
 145 l(3) = rand(1,2) // Override my vector of string
 146
 147 l(3) = null() // Remove the third element
 148
 149 lbis = list("gewurtz", "caipirina" ,"debug") // Declare a new list
 150 lter = lstcat(l,lbis) // Merge the two list
 151 size(lter) - size(lbis) - size(l)  // must be zero
 152  ]]></programlisting>
 153     </refsection>
 154     <refsection role="see also">
 155         <title>See Also</title>
 156         <simplelist type="inline">
 157             <member>
 158                 <link linkend="null">null</link>
 159             </member>
 160             <member>
 161                 <link linkend="lstcat">lstcat</link>
 162             </member>
 163             <member>
 164                 <link linkend="tlist">tlist</link>
 165             </member>
 166             <member>
 167                 <link linkend="mlist">mlist</link>
 168             </member>
 169             <member>
 170                 <link linkend="insertion">insertion</link>
 171             </member>
 172             <member>
 173                 <link linkend="extraction">extraction</link>
 174             </member>
 175             <member>
 176                 <link linkend="size">size</link>
 177             </member>
 178             <member>
 179                 <link linkend="length">length</link>
 180             </member>
 181         </simplelist>
 182     </refsection>
 183 </refentry>