update api_scilab documention with changes on pvApiCtx
[scilab.git] / scilab / modules / api_scilab / help / en_US / list_management / list_string_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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="list_string_writing_API" xml:lang="en">
14   <refnamediv>
15     <refname>String writing (Scilab gateway)</refname>
16     <refpurpose>
17       How to add matrix of string in a list.
18     </refpurpose>
19   </refnamediv>
20   <refsynopsisdiv>
21     <title>Calling Sequence</title>
22     <para>Input argument profile:</para>
23     <synopsis>SciErr createMatrixOfStringInList(void* _pvCtx, int _iVar, int* _piParent, int _iItemPos, int _iRows, int _iCols, const char* const* _pstStrings)</synopsis>
24     <para>Named variable profile:</para>
25     <synopsis>SciErr createMatrixOfStringInNamedList(void* _pvCtx, const char* _pstName, int* _piParent, int _iItemPos, int _iRows, int _iCols, const char* const* _pstStrings)</synopsis>
26   </refsynopsisdiv>
27   <refsection>
28     <title>Arguments</title>
29     <variablelist>
30       <varlistentry>
31         <term>_pvCtx</term>
32         <listitem>
33           <para>
34             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
35           </para>
36         </listitem>
37       </varlistentry>
38       <varlistentry>
39         <term>_iVar</term>
40         <listitem>
41           <para>
42             Position in the Scilab memory where you want to put the variable.
43           </para>
44         </listitem>
45       </varlistentry>
46       <varlistentry>
47         <term>_pstName</term>
48         <listitem>
49           <para>
50             Name of the variable for "named" functions.
51           </para>
52         </listitem>
53       </varlistentry>
54       <varlistentry>
55         <term>_piParent</term>
56         <listitem>
57           <para>
58             Address of the parent of the new item.
59           </para>
60         </listitem>
61       </varlistentry>
62       <varlistentry>
63         <term>_iItemPos</term>
64         <listitem>
65           <para>
66             Position of the new item in the list.
67           </para>
68         </listitem>
69       </varlistentry>
70       <varlistentry>
71         <term>_iRows</term>
72         <listitem>
73           <para>
74             Number of rows of the new variable.
75           </para>
76         </listitem>
77       </varlistentry>
78       <varlistentry>
79         <term>_iCols</term>
80         <listitem>
81           <para>
82             Number of columns of the new variable.
83           </para>
84         </listitem>
85       </varlistentry>
86       <varlistentry>
87         <term>_pstStrings</term>
88         <listitem>
89           <para>
90             Address of array of char* (size: _iCols * _iRows).
91           </para>
92         </listitem>
93       </varlistentry>
94       <varlistentry>
95         <term>SciErr</term>
96         <listitem>
97           <para>
98             Error structure where is stored errors messages history and first error number.
99           </para>
100         </listitem>
101       </varlistentry>
102     </variablelist>
103   </refsection>
104   <refsection>
105     <title>Description</title>
106     <para>This help describes how to add matrix of string in a list.</para>
107   </refsection>
108   <refsection>
109     <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/list_createlist_api.c-->
110     <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/list_createlist_api.tst-->
111     <!--Lib_name: list_createlist-->
112     <!--Func_list: list_createlist-->
113     <title>Gateway Source</title>
114     <programlisting role="code_gateway"><![CDATA[ 
115 #include "api_scilab.h"
116 int list_createlist(char *fname,unsigned long fname_len)
117 {
118         SciErr sciErr;
119         int *piAddr             = NULL;
120         int* piChild            = NULL;
121         double pdblData1[]      = {1,3,5,2,4,6};
122         double pdblData2[]      = {6,4,2,5,3,1};
123         char *pstData[]         = {"may","be","the","with","puffin","you"};
124         short psData[]          = {1,4,2,5,3,6};
125         double pdblPoly1[]      = {1};
126         double pdblPoly2[]      = {-2,-1};
127         double pdblPoly3[]      = {1,2,3};
128         double pdblPoly4[]      = {-4,-3,-2,-1};
129         double pdblPoly5[]      = {1,2,3,4,5};
130         double pdblPoly6[]      = {-6,-5,-4,-3,-2,-1};
131         double *pdblPoly[]      = {pdblPoly1, pdblPoly3, pdblPoly5, pdblPoly2, pdblPoly4, pdblPoly6};
132         int piCoef[]            = {1,3,5,2,4,6};
133         int piNbItemRow[]       = {1,2,1};
134         int piColPos[]          = {8,4,7,2};
135         double pdblSReal[]      = {1,2,3,4};
136         double pdblSImg[]       = {4,3,2,1};
137         int piBool[]            = {1,0,1,0,1,0,1,0,1};
138         double* pdblDataPtr     = NULL;
139
140         sciErr = createList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, 8, &piAddr);
141         if(sciErr.iErr)
142         {
143                 printError(&sciErr, 0);
144                 return 0;
145         }
146
147         sciErr = createComplexMatrixOfDoubleInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 1, 3, 2, pdblData1, pdblData2);
148         if(sciErr.iErr)
149         {
150                 printError(&sciErr, 0);
151                 return 0;
152         }
153
154         sciErr = createMatrixOfStringInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 2, 2, 3, pstData);
155         if(sciErr.iErr)
156         {
157                 printError(&sciErr, 0);
158                 return 0;
159         }
160
161         sciErr = createMatrixOfInteger16InList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 3, 2, 3, psData);
162         if(sciErr.iErr)
163         {
164                 printError(&sciErr, 0);
165                 return 0;
166         }
167
168         sciErr = createMatrixOfPolyInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 4, "x", 3, 2, piCoef, pdblPoly);
169         if(sciErr.iErr)
170         {
171                 printError(&sciErr, 0);
172                 return 0;
173         }
174         sciErr = createComplexSparseMatrixInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 5, 3, 10, 4, piNbItemRow, piColPos, pdblSReal, pdblSImg);
175         if(sciErr.iErr)
176         {
177                 printError(&sciErr, 0);
178                 return 0;
179         }
180
181         sciErr = createMatrixOfBooleanInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 6, 3, 3, piBool);
182         if(sciErr.iErr)
183         {
184                 printError(&sciErr, 0);
185                 return 0;
186         }
187         sciErr = createBooleanSparseMatrixInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 7, 3, 10, 4, piNbItemRow, piColPos);
188         if(sciErr.iErr)
189         {
190                 printError(&sciErr, 0);
191                 return 0;
192         }
193
194         //add list in list
195         sciErr = createListInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piAddr, 8, 3, &piChild);
196         if(sciErr.iErr)
197         {
198                 printError(&sciErr, 0);
199                 return 0;
200         }
201
202         sciErr = createMatrixOfDoubleInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piChild, 1, 3, 2, pdblData1);
203         if(sciErr.iErr)
204         {
205                 printError(&sciErr, 0);
206                 return 0;
207         }
208
209         sciErr = createSparseMatrixInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piChild, 2, 3, 10, 4, piNbItemRow, piColPos, pdblSReal);
210         if(sciErr.iErr)
211         {
212                 printError(&sciErr, 0);
213                 return 0;
214         }
215
216         pdblDataPtr     = (double*)malloc(sizeof(double) * 4);
217         pdblDataPtr[0]  = 1;
218         pdblDataPtr[1]  = 2;
219         pdblDataPtr[2]  = 3;
220         pdblDataPtr[3]  = 4;
221
222         sciErr = createPointerInList(pvApiCtx, nbInputArgument(pvApiCtx) + 1, piChild, 3, pdblDataPtr);
223         if(sciErr.iErr)
224         {
225                 printError(&sciErr, 0);
226                 return 0;
227         }
228
229         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
230         return 0;
231 }
232  ]]></programlisting>
233   </refsection>
234   <refsection>
235     <title>Scilab test script</title>
236     <programlisting role="code_scilab"><![CDATA[ 
237 size_ref    = 8;
238 type_ref    = ["constant","string","int16","polynomial", "sparse", "boolean", "boolean sparse", "list"];
239 dim_ref     = list([3,2],[2,3],[2,3],[3,2],[3,10],[3,3],[3,10],3);
240
241 l = list_createlist();
242 if size(l) <> size_ref then error("failed"), end
243 for i = 1 : size_ref
244     if typeof(l(i)) <> type_ref(i) then error("failed"), end
245     if size(l(i)) <> dim_ref(i) then error("failed"), end
246 end
247  ]]></programlisting>
248   </refsection>
249 </refentry>