bug 5588 fix
[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>Parameters</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>Any Scilab object (<literal>matrix, list,string...</literal>).</para>
38         </listitem>
39       </varlistentry>
40     </variablelist>
41   </refsection>
42   <refsection>
43     <title>Description</title>
44     <para>
45     Creates a <literal>typed-list</literal> with elements <literal>ai</literal>'s. The <literal>typ</literal>
46     argument specifies the list type. Such <literal>typed-list</literal> allow the user
47     to define new operations working on these object through scilab
48     functions. The only difference between <literal>typed-list</literal> and <literal>list</literal>
49     is the value of the type (16 instead of 15).</para>
50     <para><literal>typ(1)</literal> specifies the list type (character string used to define
51     soft coded operations)</para>
52     <para>
53     if specified <literal>typ(i)</literal> may give the <literal>i+1</literal>th element formal name</para>
54     <para>
55     Standard Operations on <literal>list</literal> work similarly for <literal>typed-list</literal>:</para>
56     <para>
57      extraction
58     : <literal>[x,y,z...]=l(v)</literal> where <literal>v</literal> is a vector of indices;
59     <literal>[x,y,z]=l(:)</literal> extracts all the elements.</para>
60     <para>
61       insertion
62     : <literal>l(i)=a</literal></para>
63     <para>
64      deletion : <literal>l(i)=null()</literal> removes the i-th
65      element of the <literal>tlist l</literal>. Note that the
66      semantics of <literal>l.x=null()</literal> is undefined, but a
67      definition can be given through the <link
68      linkend="overloading">overloading</link> mechanism.</para>
69     <para>
70      display</para>
71     <para>
72     Moreover if <literal>typ(2:n+1)</literal> are specified, user may point elements by
73     their names</para>
74     <para>
75     We give below examples where tlist are used.</para>
76     <para>
77     Linear systems are represented by specific <literal>typed-list</literal> e.g. a
78     linear system <literal>[A,B,C,D]</literal> is represented by the tlist
79     <literal>Sys=tlist(['lss';'A';'B';'C';'D';'X0';'dt'],A,B,C,D,x0,'c')</literal>
80     and this specific list may be created by the function <literal>syslin</literal>.</para>
81     <para>
82     Sys(2), Sys('A') or Sys.A is the state-matrix and Sys('dt') or Sys.dt is the time domain</para>
83     <para>
84     A rational matrix <literal>H</literal> is represented by the <literal>typed-list</literal>
85     <literal>H=tlist(['r';'num';'den';'dt'],Num,Den,[])</literal> where <literal>Num</literal> and <literal>Den</literal> are two
86     polynomial matrices and a  (e.g. continuous time) linear system with
87     transfer matrix <literal>H</literal> maybe created by <literal>syslin('c',H)</literal>.</para>
88     <para>
89     H(2), H('num') or H.num is the transfer matrix numerator</para>
90   </refsection>
91   <refsection>
92     <title>Examples</title>
93     <programlisting role="example"><![CDATA[
94 // tlist creation
95 t = tlist(["listtype","field1","field2"], [], []);
96 t.field1(1) = 10;
97 t.field1(2) = 20;
98 t.field2(1) = "Scilab";
99 t.field2(2) = "tlist";
100 t.field2(3) = "example";
101
102 // Fields contents display
103 disp(t.field1)
104 disp(t.field2)
105
106 // Generic tlist display
107 disp(t)
108
109 // Overloading display for this type of tlist
110 function %listtype_p(mytlist)
111   f = fieldnames(mytlist);
112
113   // typeof(mytlist) <=> f(1)
114   mprintf("Displaying a tlist of type: %s\n", typeof(mytlist));
115
116   mprintf("\n");
117
118   mprintf("-- Field ''%s'' --\n", f(1));
119   mprintf("Contents: %s\n", sci2exp(mytlist(f(1))));
120
121   mprintf("\n");
122
123   mprintf("-- Field ''%s'' --\n", f(2));
124   mprintf("Contents: %s\n", sci2exp(mytlist(f(2))));
125 endfunction
126
127 // Display using overloading function
128 disp(t)
129  ]]></programlisting>
130   </refsection>
131   <refsection>
132     <title>See Also</title>
133     <simplelist type="inline">
134       <member>
135         <link linkend="percent">percent</link>
136       </member>
137       <member>
138         <link linkend="syslin">syslin</link>
139       </member>
140       <member>
141         <link linkend="list">list</link>
142       </member>
143     </simplelist>
144   </refsection>
145 </refentry>