ce435e681a8432b193f9192d43198945dc2a2997
[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" version="5.0-subset Scilab" xml:lang="en" xml:id="tlist">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>tlist</refname>
19     <refpurpose> Scilab object and typed list definition.  </refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>tlist(typ,a1,....an )</synopsis>
24   </refsynopsisdiv>
25   <refsection>
26     <title>Arguments</title>
27     <variablelist>
28       <varlistentry>
29         <term>typ</term>
30         <listitem>
31           <para>Character string or vector of character strings</para>
32         </listitem>
33       </varlistentry>
34       <varlistentry>
35         <term>ai</term>
36         <listitem>
37           <para>
38             Any Scilab object (<literal>matrix, list,string...</literal>).
39           </para>
40         </listitem>
41       </varlistentry>
42     </variablelist>
43   </refsection>
44   <refsection>
45     <title>Description</title>
46     <para>
47       Creates a <literal>typed-list</literal> with elements <literal>ai</literal>'s. The <literal>typ</literal>
48       argument specifies the list type. Such <literal>typed-list</literal> allow the user
49       to define new operations working on these object through scilab
50       functions. The only difference between <literal>typed-list</literal> and <literal>list</literal>
51       is the value of the type (16 instead of 15).
52     </para>
53     <para>
54       <literal>typ(1)</literal> specifies the list type (character string used to define
55       soft coded operations)
56     </para>
57     <para>
58       if specified <literal>typ(i)</literal> may give the <literal>i+1</literal>th element formal name
59     </para>
60     <para>
61       Standard Operations on <literal>list</literal> work similarly for <literal>typed-list</literal>:
62     </para>
63     <para>
64       extraction
65       : <literal>[x,y,z...]=l(v)</literal> where <literal>v</literal> is a vector of indices;
66       <literal>[x,y,z]=l(:)</literal> extracts all the elements.
67     </para>
68     <para>
69       insertion
70       : <literal>l(i)=a</literal>
71     </para>
72     <para>
73       deletion : <literal>l(i)=null()</literal> removes the i-th
74       element of the <literal>tlist l</literal>. Note that the
75       semantics of <literal>l.x=null()</literal> is undefined, but a
76       definition can be given through the <link linkend="overloading">overloading</link> mechanism.
77     </para>
78     <para>
79       display
80     </para>
81     <para>
82       Moreover if <literal>typ(2:n+1)</literal> are specified, user may point elements by
83       their names
84     </para>
85     <para>
86       We give below examples where tlist 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 tlist
91       <literal>Sys=tlist(['lss';'A';'B';'C';'D';'X0';'dt'],A,B,C,D,x0,'c')</literal>
92       and this specific list may be created by the function <literal>syslin</literal>.
93     </para>
94     <para>
95       Sys(2), Sys('A') or Sys.A is the state-matrix and Sys('dt') or Sys.dt is the time domain
96     </para>
97     <para>
98       A rational matrix <literal>H</literal> is represented by the <literal>typed-list</literal>
99       <literal>H=tlist(['r';'num';'den';'dt'],Num,Den,[])</literal> where <literal>Num</literal> and <literal>Den</literal> are two
100       polynomial matrices and a  (e.g. continuous time) linear system with
101       transfer matrix <literal>H</literal> maybe created by <literal>syslin('c',H)</literal>.
102     </para>
103     <para>
104       H(2), H('num') or H.num 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>