99c0c215adf12104c6d05ddf2f1588a79fbe6d06
[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> Scilab object and list function definition</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 <literal>ai</literal>'s which are arbitrary Scilab
26             objects (<literal>matrix, list,...</literal>). Type of <literal>list</literal> objects is 15.
27             <literal>list()</literal> creates the empty <literal>list</literal> (0 element).
28         </para>
29     </refsection>
30     <refsection>
31         <title>Operations on lists</title>
32         <variablelist>
33             <varlistentry>
34                 <term>extraction</term>
35                 <listitem>
36                     <para>
37                         <literal>[x,y,z...]=L(v)</literal> where <literal>v</literal> is a vector of indices;
38                         <literal>[x,y,z]=L(:)</literal> extracts all the elements.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>insertion at index i</term>
44                 <listitem>
45                     <para>
46                         <literal>L(i)=a</literal> (note that it is not an error to use <literal>L(i)=a</literal>
47                         with <emphasis>i &gt; 1 + size(L)</emphasis> but some list entries are then undefined
48                         and their extraction gives raise to an error).
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>append an element in queue</term>
54                 <listitem>
55                     <para>
56                         <literal>L($+1)=e</literal>.
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>append an element in head</term>
62                 <listitem>
63                     <para>
64                         <literal>L(0)=e</literal>. (note that after this operation <literal>e</literal> is
65                         at index 1, the initial elements being shifted on the right).
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>deletion</term>
71                 <listitem>
72                     <para>
73                         <literal>L(i)=null()</literal> removes the i-th element of the list <literal>L</literal>.
74                     </para>
75                 </listitem>
76             </varlistentry>
77             <varlistentry>
78                 <term>concatenation of two lists</term>
79                 <listitem>
80                     <para>
81                         <literal>L3 = lstcat(L1,L2)</literal>.
82                     </para>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>number of elements of a list</term>
87                 <listitem>
88                     <para>
89                         you can use either <literal>nb_elm = size(L)</literal>
90                         or <literal>nb_elm = length(L)</literal>.
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>iterations with a list</term>
96                 <listitem>
97                     <para>
98                         it is possible to use a list <literal>L</literal> with a <link linkend="for">for</link> loop:
99                         <literal>for e=L,...,end</literal> is a loop with <literal>length(L)</literal>
100                         iterations, the loop variable <literal>e</literal> being equal to <literal>L(i)</literal>
101                         at the i th iteration.
102                     </para>
103                 </listitem>
104             </varlistentry>
105         </variablelist>
106     </refsection>
107     <refsection>
108         <title>Remarks</title>
109         <para>
110             Scilab provides also other kinds of list, the <link linkend="tlist">tlist</link> type (typed list) and
111             the <link linkend="mlist">mlist</link> type which are useful to define a new data type with operator
112             <link linkend="overloading">overloading</link> facilities (<link linkend="hypermatrices">hypermatrices</link> which are
113             multi-dimensionnal arrays in scilab are in fact <emphasis>mlist</emphasis>).
114         </para>
115         <para>
116             Matlab <emphasis>struct</emphasis> are also available.
117         </para>
118     </refsection>
119     <refsection>
120         <title>Examples</title>
121         <programlisting role="example"><![CDATA[ 
122 l = list(1,["a" "b"])
123 l(0) = "foo"
124 l($+1) = "hello"
125 l(2) = "toto"
126 l(3) = rand(1,2)
127 l(3) = null()
128 lbis = list("gewurtz", "caipirina" ,"debug")
129 lter = lstcat(l,lbis)
130 size(lter) - size(lbis) - size(l)  // must be zero
131  ]]></programlisting>
132     </refsection>
133     <refsection role="see also">
134         <title>See Also</title>
135         <simplelist type="inline">
136             <member>
137                 <link linkend="null">null</link>
138             </member>
139             <member>
140                 <link linkend="lstcat">lstcat</link>
141             </member>
142             <member>
143                 <link linkend="tlist">tlist</link>
144             </member>
145             <member>
146                 <link linkend="mlist">mlist</link>
147             </member>
148             <member>
149                 <link linkend="insertion">insertion</link>
150             </member>
151             <member>
152                 <link linkend="extraction">extraction</link>
153             </member>
154             <member>
155                 <link linkend="size">size</link>
156             </member>
157             <member>
158                 <link linkend="length">length</link>
159             </member>
160         </simplelist>
161     </refsection>
162 </refentry>