update api_scilab documention with changes on pvApiCtx
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / bsparse_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="bsparse_writing_API" xml:lang="en">
14   <refnamediv>
15     <refname>Boolean sparse writing (Scilab gateway)</refname>
16     <refpurpose>
17       How to add boolean sparse matrix in a gateway.
18     </refpurpose>
19   </refnamediv>
20   <refsynopsisdiv>
21     <title>Calling Sequence</title>
22     <para>Input argument profile:</para>
23     <synopsis>SciErr createBooleanSparseMatrix(void* _pvCtx, int _iVar, int _iRows, int _iCols, int _iNbItem, const int* _piNbItemRow, const int* _piColPos)</synopsis>
24     <para>Named variable profile:</para>
25     <synopsis>SciErr createNamedBooleanSparseMatrix(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, int _iNbItem, const int* _piNbItemRow, const int* _piColPos)</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>_iRows</term>
56         <listitem>
57           <para>
58             Number of rows of the new variable.
59           </para>
60         </listitem>
61       </varlistentry>
62       <varlistentry>
63         <term>_iCols</term>
64         <listitem>
65           <para>
66             Number of columns of the new variable.
67           </para>
68         </listitem>
69       </varlistentry>
70       <varlistentry>
71         <term>_iNbItem</term>
72         <listitem>
73           <para>
74             Number of non zero itmes in the sparse.
75           </para>
76         </listitem>
77       </varlistentry>
78       <varlistentry>
79         <term>_piNbItemRow</term>
80         <listitem>
81           <para>
82             Number of item in each rows (size: _iRows).
83           </para>
84         </listitem>
85       </varlistentry>
86       <varlistentry>
87         <term>_piColPos</term>
88         <listitem>
89           <para>
90             Column position for each item (size: _iNbItem).
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   <refsynopsisdiv>
105     <refsection>
106       Write directly in Scilab memory.
107     </refsection>
108     <title>Calling Sequence</title>
109     <para>Input argument profile:</para>
110     <synopsis>SciErr allocBooleanSparseMatrix(void* _pvCtx, int _iVar, int _iRows, int _iCols, int _iNbItem, int** _piNbItemRow, int** _piColPos)</synopsis>
111   </refsynopsisdiv>
112   <refsection>
113     <title>Arguments</title>
114     <variablelist>
115       <varlistentry>
116         <term>_pvCtx</term>
117         <listitem>
118           <para>
119             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
120           </para>
121         </listitem>
122       </varlistentry>
123       <varlistentry>
124         <term>_iVar</term>
125         <listitem>
126           <para>
127             Position in the Scilab memory where you want to put the variable.
128           </para>
129         </listitem>
130       </varlistentry>
131       <varlistentry>
132         <term>_iRows</term>
133         <listitem>
134           <para>
135             Number of rows of the new variable.
136           </para>
137         </listitem>
138       </varlistentry>
139       <varlistentry>
140         <term>_iCols</term>
141         <listitem>
142           <para>
143             Number of columns of the new variable.
144           </para>
145         </listitem>
146       </varlistentry>
147       <varlistentry>
148         <term>_iNbItem</term>
149         <listitem>
150           <para>
151             Number of non zero itmes in the sparse.
152           </para>
153         </listitem>
154       </varlistentry>
155       <varlistentry>
156         <term>_piNbItemRow</term>
157         <listitem>
158           <para>
159             Number of item in each rows (size: _iRows).
160           </para>
161         </listitem>
162       </varlistentry>
163       <varlistentry>
164         <term>_piColPos</term>
165         <listitem>
166           <para>
167             Column position for each item (size: _iNbItem).
168           </para>
169         </listitem>
170       </varlistentry>
171       <varlistentry>
172         <term>SciErr</term>
173         <listitem>
174           <para>
175             Error structure where is stored errors messages history and first error number.
176           </para>
177         </listitem>
178       </varlistentry>
179     </variablelist>
180   </refsection>
181   <refsection>
182     <title>Description</title>
183     <para>This help describes how to add boolean sparse matrix in a list.</para>
184   </refsection>
185   <refsection>
186     <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/read_write_bsparse_api.c-->
187     <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/read_write_bsparse_api.tst-->
188     <!--Lib_name: read_write_bsparse-->
189     <!--Func_list: read_write_bsparse-->
190     <title>Gateway Source</title>
191     <programlisting role="code_gateway"><![CDATA[ 
192 #include "api_scilab.h"
193 int read_write_bsparse(char *fname,unsigned long fname_len)
194 {
195     SciErr sciErr;
196     int i                   = 0;
197     int j                   = 0;
198     int k                   = 0;
199     //first variable info : real matrix of double
200     int iRows               = 0;
201     int iCols               = 0;
202     int *piAddr             = NULL;
203     int iNbItem             = 0;
204     int* piNbItemRow        = NULL;
205     int* piColPos           = NULL;
206     int iCol                = 0;
207     int iNewCol             = 0;
208     int iNewItem            = 0;
209     int* piNewRow           = NULL;
210     int* piNewCol           = NULL;
211
212     //check input and output arguments
213     CheckInputArgument(pvApiCtx, 1, 1);
214     CheckOutputArgument(pvApiCtx, 1, 1);
215
216     //get variable address of the first input argument
217     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
218     if(sciErr.iErr)
219     {
220         printError(&sciErr, 0);
221         return 0;
222     }
223
224     //get size and data from Scilab memory
225     sciErr = getBooleanSparseMatrix(pvApiCtx, piAddr, &iRows, &iCols, &iNbItem, &piNbItemRow, &piColPos);
226     if(sciErr.iErr)
227     {
228         printError(&sciErr, 0);
229         return 0;
230     }
231
232     //Do something with data
233     //convert %T -> %F and %F -> %T
234     iNewItem = (iRows * iCols) - iNbItem;
235     piNewRow = (int*)MALLOC(sizeof(int) * iRows);
236     piNewCol = (int*)MALLOC(sizeof(int) * iNewItem);
237
238     for(i = 0 ; i < iRows ; i++)
239     {
240         piNewRow[i] = iCols - piNbItemRow[i];
241         for(j = 0 ; j < iCols ; j++)
242         {
243             int iFind = 0;
244             for(k = 0 ; k < piNbItemRow[i] ; k++)
245             {
246                 if(piColPos[iCol + k] == (j + 1))
247                 {
248                     iFind = 1;
249                     break;
250                 }
251             }
252
253             if(iFind == 0)
254             {
255                 piNewCol[iNewCol++] = (j + 1);
256             }
257         }
258
259         iCol += piNbItemRow[i];
260     }
261
262     sciErr = createBooleanSparseMatrix(pvApiCtx, nbInputArgument(pvApiCtx) + 1, iRows, iCols, iNewItem, piNewRow, piNewCol);
263     if(sciErr.iErr)
264     {
265         printError(&sciErr, 0);
266         return 0;
267     }
268
269     AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
270     return 0;
271 }
272  ]]></programlisting>
273   </refsection>
274   <refsection>
275     <title>Scilab test script</title>
276     <programlisting role="code_scilab"><![CDATA[ 
277 a = sparse([%t, %f, %t ; %f, %t, %f ; %t, %f, %t]);
278 a_ref = sparse([%f, %t, %f ; %t, %f, %t ; %f, %t, %f]);
279
280 b = read_write_bsparse(a);
281 if or(b <> a_ref) then error("failed");end
282  ]]></programlisting>
283   </refsection>
284 </refentry>