41ea9ef1afa0fe88d2cc4c7e694f4ebd01442b39
[scilab.git] / scilab / modules / data_structures / help / en_US / tlist.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="tlist">
14     <refnamediv>
15         <refname>tlist</refname>
16         <refpurpose>Scilab object and typed list definition.  </refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>tlist(typ, a1, ..., an)</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>typ</term>
27                 <listitem>
28                     <para>a character string or vector of character strings.</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>ai</term>
33                 <listitem>
34                     <para>
35                         any Scilab object (<literal>matrix</literal>, <literal>list</literal>,
36                         <literal>string</literal>, ...).
37                     </para>
38                 </listitem>
39             </varlistentry>
40         </variablelist>
41     </refsection>
42     <refsection>
43         <title>Description</title>
44         <para>
45             <literal>tlist(typ, a1, ..., an)</literal> creates a <literal>typed-list</literal> with elements <varname>ai</varname>'s. The <varname>typ</varname> argument specifies the list type. Such <literal>typed-list</literal> allows the user to define new operations working on these object through Scilab functions. The only difference between <literal>typed-list</literal> and <literal>list</literal> is the value of the type (16 instead of 15).
46         </para>
47         <para>
48             <code>typ(1)</code> specifies the list type (character string used to define soft coded operations).
49         </para>
50         <para>
51             If specified <code>typ(i)</code> may give the <literal>(i+1)</literal>-th element formal name.
52         </para>
53         <para>
54             Standard Operations on <literal>list</literal> work similarly for <literal>typed-list</literal>:
55         </para>
56         <para>
57             extraction:
58         </para>
59         <para>
60             <literal>[x, y, z, ...]=l(v)</literal> where <literal>v</literal> is a vector of indices;
61             <literal>[x, y, z]=l(:)</literal> extracts all the elements.
62         </para>
63         <para>
64             insertion:
65         </para>
66         <para>
67             <literal>l(i)=a</literal>
68         </para>
69         <para>
70             deletion:
71         </para>
72         <para>
73             <code>l(i)=null()</code> removes the <literal>i</literal>-th
74             element of the <literal>tlist</literal> <literal>l</literal>.              <note>
75                 Note that the  semantics of <code>l.x=null()</code> is undefined, but a definition can be given through the <link linkend="overloading">overloading</link> mechanism.
76             </note>
77         </para>
78         <para>
79             display.
80         </para>
81         <para>
82             Moreover if <code>typ(2:n+1)</code> are specified, user may point elements by
83             their names.
84         </para>
85         <para>
86             We give below examples where <literal>tlist</literal> are used.
87         </para>
88         <para>
89             Linear systems are represented by specific <literal>typed-list</literal> e.g. a
90             linear system <literal>[A,B,C,D]</literal> is represented by the <literal>tlist</literal>
91             <code>Sys=tlist(['lss';'A';'B';'C';'D';'X0';'dt'],A,B,C,D,x0,'c')</code>
92             and this specific list may be created by the function <function>syslin</function>.
93         </para>
94         <para>
95             <code>Sys(2)</code>, <code>Sys('A')</code> or <code>Sys.A</code> is the state-matrix and <code>Sys('dt')</code> or <code>Sys.dt</code> is the time domain.
96         </para>
97         <para>
98             A rational matrix <literal>H</literal> is represented by the <literal>typed-list</literal>
99             <code>H=rlist(Num,Den,[])</code> where <literal>Num</literal> and <literal>Den</literal> are two
100             polynomial matrices and a continuous time linear system with
101             transfer matrix <literal>H</literal> may be created by <code>syslin('c',H)</code>.
102         </para>
103         <para>
104             <code>H(2)</code>, <code>H('num')</code> or <code>H.num</code> is the transfer matrix numerator.
105         </para>
106     </refsection>
107     <refsection>
108         <title>Examples</title>
109         <programlisting role="example"><![CDATA[
110 // tlist creation
111 t = tlist(["listtype","field1","field2"], [], []);
112 t.field1(1) = 10;
113 t.field1(2) = 20;
114 t.field2(1) = "Scilab";
115 t.field2(2) = "tlist";
116 t.field2(3) = "example";
117  
118 // Fields contents display
119 disp(t.field1)
120 disp(t.field2)
121  
122 // Generic tlist display
123 disp(t)
124  
125 // Overloading display for this type of tlist
126 function %listtype_p(mytlist)
127   f = fieldnames(mytlist);
128  
129   // typeof(mytlist) <=> f(1)
130   mprintf("Displaying a tlist of type: %s\n", typeof(mytlist));
131  
132   mprintf("\n");
133  
134   mprintf("-- Field ''%s'' --\n", f(1));
135   mprintf("Contents: %s\n", sci2exp(mytlist(f(1))));
136  
137   mprintf("\n");
138  
139   mprintf("-- Field ''%s'' --\n", f(2));
140   mprintf("Contents: %s\n", sci2exp(mytlist(f(2))));
141 endfunction
142  
143 // Display using overloading function
144 disp(t)
145  ]]></programlisting>
146     </refsection>
147     <refsection role="see also">
148         <title>See Also</title>
149         <simplelist type="inline">
150             <member>
151                 <link linkend="percent">percent</link>
152             </member>
153             <member>
154                 <link linkend="syslin">syslin</link>
155             </member>
156             <member>
157                 <link linkend="list">list</link>
158             </member>
159             <member>
160                 <link linkend="mlist">mlist</link>
161             </member>
162         </simplelist>
163     </refsection>
164 </refentry>