Improve the list example
[scilab.git] / 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>