afc0c766d0e19fbbebdf98189635c7cf23ab29ba
[scilab.git] / scilab / modules / data_structures / help / en_US / mlist.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) 2007-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="mlist">
14     <refnamediv>
15         <refname>mlist</refname>
16         <refpurpose>Scilab object, matrix oriented typed list
17             definition.
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>mlist(typ,a1,....an )</synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>Arguments</title>
26         <variablelist>
27             <varlistentry>
28                 <term>typ</term>
29                 <listitem>
30                     <para>vector of character strings</para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>ai</term>
35                 <listitem>
36                     <para>
37                         any Scilab object (<literal>matrix, list,string...</literal>).
38                     </para>
39                 </listitem>
40             </varlistentry>
41         </variablelist>
42     </refsection>
43     <refsection>
44         <title>Description</title>
45         <para>
46             <literal>mlist</literal> object are very similar to <link linkend="tlist">tlist</link> objects.
47             The only difference concerns the <link linkend="extraction">extraction</link>  and <link linkend="insertion">insertion</link>   syntax:
48             if <literal>M</literal> is an mlist, for any index <literal>i</literal> which is
49             not a field name, <literal>M(i)</literal> is no more the <literal>i</literal>th
50             field of the list.
51         </para>
52         <para> The semantic of the extraction and insertion syntax should be given by
53             an <link linkend="overloading">overloading</link> functions.
54         </para>
55         <para>
56             The overloading function for extraction syntax <literal>b=a(i1,...,in)</literal>
57             has the following calling sequence: <literal>b=%&lt;type_of_a&gt;_e_(i1,...,in,a)</literal> 
58         </para>
59         <para>and the syntax
60             <literal>[x1,..,xm]=a(i1,...,in)</literal> has the following calling sequence:
61             <literal>[x1,..,xm]=%&lt;type_of_a&gt;_e_(i1,...,in,a)</literal>
62         </para>
63         <para/>
64         <para> The overloading function associated to the insertion syntax
65             <literal>a(i1,...,in)=b</literal>  has the following calling sequence:
66             <literal>a=%&lt;type_of_b&gt;_i_&lt;type_of_a&gt;(i1,...,in,b,a)</literal>. 
67         </para>
68         <para/>
69         <para>mlist fields must then be designed by their names. They can also be
70             handled using the <literal>getfield</literal> and <literal>setfield</literal>
71             functions.
72         </para>
73     </refsection>
74     <refsection>
75         <title>Examples</title>
76         <programlisting role="example"><![CDATA[ 
77 M=mlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);
78 //define display
79 function %V_p(M),disp(M.name+':'+string(M.value)),endfunction
80
81 //define extraction operation
82 function r=%V_e(varargin)
83   M=varargin($)
84   r=mlist(['V','name','value'],M.name(varargin(1:$-1)),M.value(varargin(1:$-1)))
85 endfunction
86 M(2,:) // the second row of  M
87 M.value
88
89 //define insertion operations
90 function M=%V_i_V(varargin)
91   M=varargin($)
92   N=varargin($-1)
93   M.value(varargin(1:$-2))=N.value
94   M.name(varargin(1:$-2))=N.name
95 endfunction
96 M(1,1)=M(2,2)
97
98 function M=%s_i_V(varargin) //insertion of a regular matrix into a V matrix
99   M=varargin($)
100   N=varargin($-1)
101   M.value(varargin(1:$-2))=N
102   M.name(varargin(1:$-2))=emptystr(N)
103 endfunction
104 M(1,1)=44
105
106 //tlist case
107 M=tlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);
108 M(2)
109 M(2)='a'+string([1 2;3 4])
110
111 M('name')
112  ]]></programlisting>
113     </refsection>
114     <refsection role="see also">
115         <title>See Also</title>
116         <simplelist type="inline">
117             <member>
118                 <link linkend="tlist">tlist</link>
119             </member>
120             <member>
121                 <link linkend="list">list</link>
122             </member>
123             <member>
124                 <link linkend="overloading">overloading</link>
125             </member>
126             <member>
127                 <link linkend="getfield">getfield</link>
128             </member>
129             <member>
130                 <link linkend="setfield">setfield</link>
131             </member>
132         </simplelist>
133     </refsection>
134 </refentry>