f3cbcb3d802a1dadb6ac1898492eec37bd79ba60
[scilab.git] / scilab / modules / api_scilab / help / en_US / list_management / list_double_writing_api.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) 2009  - DIGITEO - Antoine ELIAS
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 version="5.0-subset Scilab" xml:id="list_double_writing_API"
14           xml:lang="en" xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20
21     <refnamediv>
22         <refname>Double writing (Scilab gateway)</refname>
23
24         <refpurpose>
25             How to add matrix of double in a list.
26         </refpurpose>
27     </refnamediv>
28     <refsection>
29         <title>Description</title>
30         <para>This help describes how to add matrix of double in a list.</para>
31         <para>There are 2 types of functions which can be used to write in the memory of Scilab.</para>
32     </refsection>
33     <refsection>
34         <title>Create from existing data</title>
35         <programlisting><![CDATA[
36 int createMatrixOfDoubleInList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, double* _pdblReal)
37 int createComplexMatrixOfDoubleInList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, double* _pdblReal, double* _pdblImg)
38 ]]></programlisting>
39     </refsection>
40     <refsection>
41         <title>Parameters</title>
42         <variablelist>
43             <varlistentry>
44                 <term>_iVar</term>
45                 <listitem>
46                     <para>
47                         Position in the Scilab memory where you want to put the variable.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>_piParent</term>
53                 <listitem>
54                     <para>
55                         Address of the parent of the new item.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>_iItemPos</term>
61                 <listitem>
62                     <para>
63                         Position of the new item in the list.
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>_iRows</term>
69                 <listitem>
70                     <para>
71                         Number of rows of the new variable.
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>_iCols</term>
77                 <listitem>
78                     <para>
79                         Number of columns of the new variable.
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>_pdblReal</term>
85                 <listitem>
86                     <para>
87                         Address of real data array (size: _iCols * _iRows).
88                     </para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>_pdblImg</term>
93                 <listitem>
94                     <para>
95                         Address of imaginary data array (size: _iCols * _iRows).
96                     </para>
97                 </listitem>
98             </varlistentry>
99         </variablelist>
100     </refsection>
101     <refsection>
102         <title>Write directly in Scilab memory</title>
103         <programlisting><![CDATA[
104 int allocMatrixOfDoubleInList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, double** _pdblReal)
105 int allocComplexMatrixOfDoubleInList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, double** _pdblReal, double** _pdblImg)
106 ]]></programlisting>
107     </refsection>
108     <refsection>
109         <title>Parameters</title>
110         <variablelist>
111             <varlistentry>
112                 <term>_iVar</term>
113                 <listitem>
114                     <para>
115                         Position in the Scilab memory where you want to put the variable.
116                     </para>
117                 </listitem>
118             </varlistentry>
119             <varlistentry>
120                 <term>_piParent</term>
121                 <listitem>
122                     <para>
123                         Address of the parent of the new item.
124                     </para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>_iItemPos</term>
129                 <listitem>
130                     <para>
131                         Position of the new item in the list.
132                     </para>
133                 </listitem>
134             </varlistentry>
135             <varlistentry>
136                 <term>_iRows</term>
137                 <listitem>
138                     <para>
139                         Number of rows of the new variable.
140                     </para>
141                 </listitem>
142             </varlistentry>
143             <varlistentry>
144                 <term>_iCols</term>
145                 <listitem>
146                     <para>
147                         Number of columns of the new variable.
148                     </para>
149                 </listitem>
150             </varlistentry>
151             <varlistentry>
152                 <term>_pdblReal</term>
153                 <listitem>
154                     <para>
155                         Return address of real data array (size: _iCols * _iRows).
156                     </para>
157                 </listitem>
158             </varlistentry>
159             <varlistentry>
160                 <term>_pdblImg</term>
161                 <listitem>
162                     <para>
163                         Return address of imaginary data array (size: _iCols * _iRows).
164                     </para>
165                 </listitem>
166             </varlistentry>
167         </variablelist>
168     </refsection>
169     <refsection>
170         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/list_createlist_api.c-->
171         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/list_createlist_api.tst-->
172         <!--Lib_name: list_createlist-->
173         <!--Func_list: list_createlist-->
174         <title>Gateway Source</title>
175         <programlisting role="code_gateway">
176             <![CDATA[
177 int list_createlist(char *fname,unsigned long fname_len)
178 {
179     int iRet                = 0;
180
181     int *piAddr             = NULL;
182     int* piChild            = NULL;
183     double pdblData1[]      = {1,3,5,2,4,6};
184     double pdblData2[]      = {6,4,2,5,3,1};
185     char *pstData[]         = {"may","be","the","with","puffin","you"};
186     short psData[]          = {1,4,2,5,3,6};
187     double pdblPoly1[]      = {1};
188     double pdblPoly2[]      = {-2,-1};
189     double pdblPoly3[]      = {1,2,3};
190     double pdblPoly4[]      = {-4,-3,-2,-1};
191     double pdblPoly5[]      = {1,2,3,4,5};
192     double pdblPoly6[]      = {-6,-5,-4,-3,-2,-1};
193     double *pdblPoly[]      = {pdblPoly1, pdblPoly3, pdblPoly5, pdblPoly2, pdblPoly4, pdblPoly6};
194     int piCoef[]            = {1,3,5,2,4,6};
195     int piNbItemRow[]       = {1,2,1};
196     int piColPos[]          = {8,4,7,2};
197     double pdblSReal[]      = {1,2,3,4};
198     double pdblSImg[]       = {4,3,2,1};
199     int piBool[]            = {1,0,1,0,1,0,1,0,1};
200     double* pdblDataPtr     = NULL;
201     
202     
203     iRet = createList(1, 8, &piAddr);
204     if(iRet)
205     {
206         return 1;
207     }
208
209     iRet = createComplexMatrixOfDoubleInList(Rhs + 1, piAddr, 1, 3, 2, pdblData1, pdblData2);
210     if(iRet)
211     {
212         return 1;
213     }
214
215     iRet = createMatrixOfStringInList(Rhs + 1, piAddr, 2, 2, 3, pstData);
216     if(iRet)
217     {
218         return 1;
219     }
220
221     iRet = createMatrixOfInteger16InList(Rhs + 1, piAddr, 3, 2, 3, psData);
222     if(iRet)
223     {
224         return 1;
225     }
226
227     iRet = createMatrixOfPolyInList(Rhs + 1, piAddr, 4, "x", 3, 2, piCoef, pdblPoly);
228     if(iRet)
229     {
230         return 1;
231     }
232
233     iRet = createComplexSparseMatrixInList(Rhs + 1, piAddr, 5, 3, 10, 4, piNbItemRow, piColPos, pdblSReal, pdblSImg);
234     if(iRet)
235     {
236         return 1;
237     }
238
239     iRet = createMatrixOfBooleanInList(Rhs + 1, piAddr, 6, 3, 3, piBool);
240     if(iRet)
241     {
242         return 1;
243     }
244
245     iRet = createBooleanSparseMatrixInList(Rhs + 1, piAddr, 7, 3, 10, 4, piNbItemRow, piColPos);
246     if(iRet)
247     {
248         return 1;
249     }
250
251     //add list in list
252     iRet = createListInList(Rhs + 1, piAddr, 8, 3, &piChild);
253     if(iRet)
254     {
255         return 1;
256     }
257
258     iRet = createMatrixOfDoubleInList(Rhs + 1, piChild, 1, 3, 2, pdblData1);
259     if(iRet)
260     {
261         return 1;
262     }
263
264     iRet = createSparseMatrixInList(Rhs + 1, piChild, 2, 3, 10, 4, piNbItemRow, piColPos, pdblSReal);
265     if(iRet)
266     {
267         return 1;
268     }
269
270     pdblDataPtr     = (double*)malloc(sizeof(double) * 4);
271     pdblDataPtr[0]  = 1;
272     pdblDataPtr[1]  = 2;
273     pdblDataPtr[2]  = 3;
274     pdblDataPtr[3]  = 4;
275     
276     iRet = createPointerInList(Rhs + 1, piChild, 3, pdblDataPtr);
277     if(iRet)
278     {
279         return 1;
280     }
281
282     LhsVar(1) = 1;
283     return 0;
284 }
285         ]]>
286         </programlisting>
287     </refsection>
288
289     <refsection>
290         <title>Scilab test script</title>
291         <programlisting role="code_scilab">
292             <![CDATA[
293 size_ref    = 8;
294 type_ref    = ["constant","string","int16","polynomial", "sparse", "boolean", "boolean sparse", "list"];
295 dim_ref     = list([3,2],[2,3],[2,3],[3,2],[3,10],[3,3],[3,10],3);
296
297 l = list_createlist();
298 if size(l) <> size_ref then error("failed"), end
299 for i = 1 : size_ref
300     if typeof(l(i)) <> type_ref(i) then error("failed"), end
301     if size(l(i)) <> dim_ref(i) then error("failed"), end
302 end
303
304             ]]>
305         </programlisting>
306     </refsection>
307 </refentry>