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>.
  75             <note>
  76                 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.
  77             </note>
  78         </para>
  79         <para>
  80             display.
  81         </para>
  82         <para>
  83             Moreover if <code>typ(2:n+1)</code> are specified, user may
  84             point elements by their names.
  85         </para>
  86         <para>
  87             We give below examples where <literal>tlist</literal> are used.
  88         </para>
  89         <para>
  90             Linear systems are represented by specific <literal>typed-list</literal> e.g. a
  91             linear system <literal>[A,B,C,D]</literal> is represented by the <literal>tlist</literal>
  92             <code>Sys=tlist(['lss';'A';'B';'C';'D';'X0';'dt'],A,B,C,D,x0,'c')</code>
  93             and this specific list may be created by the function <function>syslin</function>.
  94         </para>
  95         <para>
  96             <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.
  97         </para>
  98         <para>
  99             A rational matrix <literal>H</literal> is represented by the <literal>typed-list</literal>
 100             <code>H=rlist(Num,Den,[])</code> where <literal>Num</literal> and <literal>Den</literal> are two
 101             polynomial matrices and a continuous time linear system with
 102             transfer matrix <literal>H</literal> may be created by <code>syslin('c',H)</code>.
 103         </para>
 104         <para>
 105             <code>H(2)</code>, <code>H('num')</code> or <code>H.num</code> is the transfer matrix numerator.
 106         </para>
 107     </refsection>
 108     <refsection>
 109         <title>Examples</title>
 110         <programlisting role="example"><![CDATA[
 111 // tlist creation
 112 t = tlist(["listtype","field1","field2"], [], []);
 113 t.field1(1) = 10;
 114 t.field1(2) = 20;
 115 t.field2(1) = "Scilab";
 116 t.field2(2) = "tlist";
 117 t.field2(3) = "example";
 118
 119 // Fields contents display
 120 disp(t.field1)
 121 disp(t.field2)
 122
 123 // Generic tlist display
 124 disp(t)
 125
 126 // Overloading display for this type of tlist
 127 function %listtype_p(mytlist)
 128   f = fieldnames(mytlist);
 129
 130   // typeof(mytlist) <=> f(1)
 131   mprintf("Displaying a tlist of type: %s\n", typeof(mytlist));
 132
 133   mprintf("\n");
 134
 135   mprintf("-- Field ''%s'' --\n", f(1));
 136   mprintf("Contents: %s\n", sci2exp(mytlist(f(1))));
 137
 138   mprintf("\n");
 139
 140   mprintf("-- Field ''%s'' --\n", f(2));
 141   mprintf("Contents: %s\n", sci2exp(mytlist(f(2))));
 142 endfunction
 143
 144 // Display using overloading function
 145 disp(t)
 146  ]]></programlisting>
 147     </refsection>
 148     <refsection role="see also">
 149         <title>See Also</title>
 150         <simplelist type="inline">
 151             <member>
 152                 <link linkend="percent">percent</link>
 153             </member>
 154             <member>
 155                 <link linkend="syslin">syslin</link>
 156             </member>
 157             <member>
 158                 <link linkend="list">list</link>
 159             </member>
 160             <member>
 161                 <link linkend="mlist">mlist</link>
 162             </member>
 163         </simplelist>
 164     </refsection>
 165 </refentry>