fc3fe635000852383e1642db93b42679db899a6b
[scilab.git] / scilab / modules / api_scilab / help / en_US / list_management / list_integer_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_integer_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>Integer writing (Scilab gateway)</refname>
23
24         <refpurpose>
25             How to add matrix of integer in a list.
26         </refpurpose>
27     </refnamediv>
28     <refsection>
29         <title>Description</title>
30         <para>This help describes how to add matrix of integer 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 createMatrixOfInteger8InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, char* _pcData)
37 int createMatrixOfInteger16InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, short* _psData)
38 int createMatrixOfInteger32InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, int* _piData)
39 int createMatrixOfUnsignedInteger8InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, unsigned char* _pucData)
40 int createMatrixOfUnsignedInteger16InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, unsigned short* _pusData)
41 int createMatrixOfUnsignedInteger32InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, unsigned int* _puiData)
42 ]]></programlisting>
43     </refsection>
44     <refsection>
45         <title>Parameters</title>
46         <variablelist>
47             <varlistentry>
48                 <term>_iVar</term>
49                 <listitem>
50                     <para>
51                         Position in the Scilab memory where you want to put the variable.
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>_piParent</term>
57                 <listitem>
58                     <para>
59                         Address of the parent of the new item.
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>_iItemPos</term>
65                 <listitem>
66                     <para>
67                         Position of the new item in the list.
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>_iRows</term>
73                 <listitem>
74                     <para>
75                         Number of rows of the new variable.
76                     </para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>_iCols</term>
81                 <listitem>
82                     <para>
83                         Number of columns of the new variable.
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>_pcData8, _psData16, _piData32, _pucData8, _pusData16, _puiData32</term>
89                 <listitem>
90                     <para>
91                         Address of data array (size: _iCols * _iRows)
92                     </para>
93                 </listitem>
94             </varlistentry>
95         </variablelist>
96     </refsection>
97     <refsection>
98         <title>Write directly in Scilab memory</title>
99         <programlisting><![CDATA[
100 int allocMatrixOfInteger8InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, char** _pcData)
101 int allocMatrixOfInteger16InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, short** _psData)
102 int allocMatrixOfInteger32InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, int** _piData)
103 int allocMatrixOfUnsignedInteger8InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, unsigned char** _pucData)
104 int allocMatrixOfUnsignedInteger16InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, unsigned short** _pusData)
105 int allocMatrixOfUnsignedInteger32InList(int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, unsigned int** _puiData)
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>_pcData8, _psData16, _piData32, _pucData8, _pusData16, _puiData32</term>
153                 <listitem>
154                     <para>
155                         Return address of data array (size: _iCols * _iRows)
156                     </para>
157                 </listitem>
158             </varlistentry>
159         </variablelist>
160     </refsection>
161     <refsection>
162         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/list_createlist_api.c-->
163         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/list_createlist_api.tst-->
164         <!--Lib_name: list_createlist-->
165         <!--Func_list: list_createlist-->
166         <title>Gateway Source</title>
167         <programlisting role="code_gateway">
168             <![CDATA[
169 int list_createlist(char *fname,unsigned long fname_len)
170 {
171     int iRet                = 0;
172
173     int *piAddr             = NULL;
174     int* piChild            = NULL;
175     double pdblData1[]      = {1,3,5,2,4,6};
176     double pdblData2[]      = {6,4,2,5,3,1};
177     char *pstData[]         = {"may","be","the","with","puffin","you"};
178     short psData[]          = {1,4,2,5,3,6};
179     double pdblPoly1[]      = {1};
180     double pdblPoly2[]      = {-2,-1};
181     double pdblPoly3[]      = {1,2,3};
182     double pdblPoly4[]      = {-4,-3,-2,-1};
183     double pdblPoly5[]      = {1,2,3,4,5};
184     double pdblPoly6[]      = {-6,-5,-4,-3,-2,-1};
185     double *pdblPoly[]      = {pdblPoly1, pdblPoly3, pdblPoly5, pdblPoly2, pdblPoly4, pdblPoly6};
186     int piCoef[]            = {1,3,5,2,4,6};
187     int piNbItemRow[]       = {1,2,1};
188     int piColPos[]          = {8,4,7,2};
189     double pdblSReal[]      = {1,2,3,4};
190     double pdblSImg[]       = {4,3,2,1};
191     int piBool[]            = {1,0,1,0,1,0,1,0,1};
192     double* pdblDataPtr     = NULL;
193     
194     
195     iRet = createList(1, 8, &piAddr);
196     if(iRet)
197     {
198         return 1;
199     }
200
201     iRet = createComplexMatrixOfDoubleInList(Rhs + 1, piAddr, 1, 3, 2, pdblData1, pdblData2);
202     if(iRet)
203     {
204         return 1;
205     }
206
207     iRet = createMatrixOfStringInList(Rhs + 1, piAddr, 2, 2, 3, pstData);
208     if(iRet)
209     {
210         return 1;
211     }
212
213     iRet = createMatrixOfInteger16InList(Rhs + 1, piAddr, 3, 2, 3, psData);
214     if(iRet)
215     {
216         return 1;
217     }
218
219     iRet = createMatrixOfPolyInList(Rhs + 1, piAddr, 4, "x", 3, 2, piCoef, pdblPoly);
220     if(iRet)
221     {
222         return 1;
223     }
224
225     iRet = createComplexSparseMatrixInList(Rhs + 1, piAddr, 5, 3, 10, 4, piNbItemRow, piColPos, pdblSReal, pdblSImg);
226     if(iRet)
227     {
228         return 1;
229     }
230
231     iRet = createMatrixOfBooleanInList(Rhs + 1, piAddr, 6, 3, 3, piBool);
232     if(iRet)
233     {
234         return 1;
235     }
236
237     iRet = createBooleanSparseMatrixInList(Rhs + 1, piAddr, 7, 3, 10, 4, piNbItemRow, piColPos);
238     if(iRet)
239     {
240         return 1;
241     }
242
243     //add list in list
244     iRet = createListInList(Rhs + 1, piAddr, 8, 3, &piChild);
245     if(iRet)
246     {
247         return 1;
248     }
249
250     iRet = createMatrixOfDoubleInList(Rhs + 1, piChild, 1, 3, 2, pdblData1);
251     if(iRet)
252     {
253         return 1;
254     }
255
256     iRet = createSparseMatrixInList(Rhs + 1, piChild, 2, 3, 10, 4, piNbItemRow, piColPos, pdblSReal);
257     if(iRet)
258     {
259         return 1;
260     }
261
262     pdblDataPtr     = (double*)malloc(sizeof(double) * 4);
263     pdblDataPtr[0]  = 1;
264     pdblDataPtr[1]  = 2;
265     pdblDataPtr[2]  = 3;
266     pdblDataPtr[3]  = 4;
267     
268     iRet = createPointerInList(Rhs + 1, piChild, 3, pdblDataPtr);
269     if(iRet)
270     {
271         return 1;
272     }
273
274     LhsVar(1) = 1;
275     return 0;
276 }
277         ]]>
278         </programlisting>
279     </refsection>
280
281     <refsection>
282         <title>Scilab test script</title>
283         <programlisting role="code_scilab">
284             <![CDATA[
285 size_ref    = 8;
286 type_ref    = ["constant","string","int16","polynomial", "sparse", "boolean", "boolean sparse", "list"];
287 dim_ref     = list([3,2],[2,3],[2,3],[3,2],[3,10],[3,3],[3,10],3);
288
289 l = list_createlist();
290 if size(l) <> size_ref then error("failed"), end
291 for i = 1 : size_ref
292     if typeof(l(i)) <> type_ref(i) then error("failed"), end
293     if size(l(i)) <> dim_ref(i) then error("failed"), end
294 end
295
296             ]]>
297         </programlisting>
298     </refsection>
299 </refentry>