Revision of help pages of module "data_structures" (en_US, ru_RU).
[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>a 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</literal>, <literal>list</literal>, <literal>string</literal>, ...).
38                     </para>
39                 </listitem>
40             </varlistentry>
41         </variablelist>
42     </refsection>
43     <refsection>
44         <title>Description</title>
45         <para>
46             <link linkend="mlist">mlist</link> object is very similar to <link linkend="tlist">tlist</link> object.
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 <literal>mlist</literal>, 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>
53             The semantic of the extraction and insertion syntax should be given by
54             an <link linkend="overloading">overloading</link> function.
55         </para>
56         <para>
57             The overloading function for extraction syntax <literal>b=a(i1, ..., in)</literal>
58             has the following calling sequence: <literal>b=%&lt;type_of_a&gt;_e_(i1, ..., in, a)</literal>
59         </para>
60         <para>and the syntax
61             <literal>[x1, ..., xm]=a(i1, ..., in)</literal> has the following calling sequence:
62             <literal>[x1, ..., xm]=%&lt;type_of_a&gt;_e_(i1, ..., in,a)</literal>
63         </para>
64         <para/>
65         <para> The overloading function associated to the insertion syntax
66             <literal>a(i1, ..., in)=b</literal>  has the following calling sequence:
67             <literal>a=%&lt;type_of_b&gt;_i_&lt;type_of_a&gt;(i1, ..., in, b, a)</literal>.
68         </para>
69         <para/>
70         <para><literal>mlist</literal> fields must then be designed by their names. They can also be
71             handled using the <function>getfield</function> and <function>setfield</function>
72             functions.
73         </para>
74     </refsection>
75     <refsection>
76         <title>Examples</title>
77         <programlisting role="example"><![CDATA[
78 M=mlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);
79 //define display
80 function %V_p(M),disp(M.name+':'+string(M.value)),endfunction
81  
82 //define extraction operation
83 function r=%V_e(varargin)
84   M=varargin($)
85   r=mlist(['V','name','value'],M.name(varargin(1:$-1)),M.value(varargin(1:$-1)))
86 endfunction
87 M(2,:) // the second row of  M
88 M.value
89  
90 //define insertion operations
91 function M=%V_i_V(varargin)
92   M=varargin($)
93   N=varargin($-1)
94   M.value(varargin(1:$-2))=N.value
95   M.name(varargin(1:$-2))=N.name
96 endfunction
97 M(1,1)=M(2,2)
98  
99 function M=%s_i_V(varargin) //insertion of a regular matrix into a V matrix
100   M=varargin($)
101   N=varargin($-1)
102   M.value(varargin(1:$-2))=N
103   M.name(varargin(1:$-2))=emptystr(N)
104 endfunction
105 M(1,1)=44
106  
107 //tlist case
108 M=tlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);
109 M(2)
110 M(2)='a'+string([1 2;3 4])
111  
112 M('name')
113  ]]></programlisting>
114     </refsection>
115     <refsection role="see also">
116         <title>See Also</title>
117         <simplelist type="inline">
118             <member>
119                 <link linkend="tlist">tlist</link>
120             </member>
121             <member>
122                 <link linkend="list">list</link>
123             </member>
124             <member>
125                 <link linkend="overloading">overloading</link>
126             </member>
127             <member>
128                 <link linkend="getfield">getfield</link>
129             </member>
130             <member>
131                 <link linkend="setfield">setfield</link>
132             </member>
133         </simplelist>
134     </refsection>
135 </refentry>