Revision of help pages of module "data_structures" (en_US, ru_RU).
[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"])
133 l(0) = "foo"
134 l($+1) = "hello"
135 l(2) = "toto"
136 l(3) = rand(1,2)
137 l(3) = null()
138 lbis = list("gewurtz", "caipirina" ,"debug")
139 lter = lstcat(l,lbis)
140 size(lter) - size(lbis) - size(l)  // must be zero
141  ]]></programlisting>
142     </refsection>
143     <refsection role="see also">
144         <title>See Also</title>
145         <simplelist type="inline">
146             <member>
147                 <link linkend="null">null</link>
148             </member>
149             <member>
150                 <link linkend="lstcat">lstcat</link>
151             </member>
152             <member>
153                 <link linkend="tlist">tlist</link>
154             </member>
155             <member>
156                 <link linkend="mlist">mlist</link>
157             </member>
158             <member>
159                 <link linkend="insertion">insertion</link>
160             </member>
161             <member>
162                 <link linkend="extraction">extraction</link>
163             </member>
164             <member>
165                 <link linkend="size">size</link>
166             </member>
167             <member>
168                 <link linkend="length">length</link>
169             </member>
170         </simplelist>
171     </refsection>
172 </refentry>