update api_scilab documention with changes on pvApiCtx
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / bsparse_reading_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_reading_API" xml:lang="en">
14   <refnamediv>
15     <refname>Boolean sparse reading (Scilab gateway)</refname>
16     <refpurpose>
17       How to read boolean sparse in a gateway.
18     </refpurpose>
19   </refnamediv>
20   <refsynopsisdiv>
21     <title>Calling Sequence</title>
22     <para>Input argument profile:</para>
23     <synopsis>SciErr getBooleanSparseMatrix(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piNbItem, int** _piNbItemRow, int** _piColPos)</synopsis>
24     <para>Named variable profile:</para>
25     <synopsis>SciErr readNamedBooleanSparseMatrix(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piNbItem, int* _piNbItemRow, 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>_piAddress</term>
40         <listitem>
41           <para>
42             Address of the Scilab 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>_piRows</term>
56         <listitem>
57           <para>
58             Return number of rows of the variable.
59           </para>
60         </listitem>
61       </varlistentry>
62       <varlistentry>
63         <term>_piCols</term>
64         <listitem>
65           <para>
66             Return number of columns of the variable.
67           </para>
68         </listitem>
69       </varlistentry>
70       <varlistentry>
71         <term>_piNbItem</term>
72         <listitem>
73           <para>
74             Return number of non zero value.
75           </para>
76         </listitem>
77       </varlistentry>
78       <varlistentry>
79         <term>_piNbItemRow</term>
80         <listitem>
81           <para>
82             Return number of item in each rows (size: _iRows).
83             For "Named" function, _piNbItemRow must be allocated before calling function.
84           </para>
85         </listitem>
86       </varlistentry>
87       <varlistentry>
88         <term>_piColPos</term>
89         <listitem>
90           <para>
91             Return column position for each item (size: _iNbItem).
92             For "Named" function, _piColPos must be allocated before calling function.
93           </para>
94         </listitem>
95       </varlistentry>
96       <varlistentry>
97         <term>SciErr</term>
98         <listitem>
99           <para>
100             Error structure where is stored errors messages history and first error number.
101           </para>
102         </listitem>
103       </varlistentry>
104     </variablelist>
105   </refsection>
106   <refsection>
107     <title>Description</title>
108     <para>This help describes how to read boolean sparse.</para>
109   </refsection>
110   <refsection>
111     <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/read_write_bsparse_api.c-->
112     <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/read_write_bsparse_api.tst-->
113     <!--Lib_name: read_write_bsparse-->
114     <!--Func_list: read_write_bsparse-->
115     <title>Gateway Source</title>
116     <programlisting role="code_gateway"><![CDATA[ 
117 #include "api_scilab.h"
118 int read_write_bsparse(char *fname,unsigned long fname_len)
119 {
120     SciErr sciErr;
121     int i                   = 0;
122     int j                   = 0;
123     int k                   = 0;
124     //first variable info : real matrix of double
125     int iRows               = 0;
126     int iCols               = 0;
127     int *piAddr             = NULL;
128     int iNbItem             = 0;
129     int* piNbItemRow        = NULL;
130     int* piColPos           = NULL;
131     int iCol                = 0;
132     int iNewCol             = 0;
133     int iNewItem            = 0;
134     int* piNewRow           = NULL;
135     int* piNewCol           = NULL;
136
137     //check input and output arguments
138     CheckInputArgument(pvApiCtx, 1, 1);
139     CheckOutputArgument(pvApiCtx, 1, 1);
140
141     //get variable address of the first input argument
142     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
143     if(sciErr.iErr)
144     {
145         printError(&sciErr, 0);
146         return 0;
147     }
148
149     //get size and data from Scilab memory
150     sciErr = getBooleanSparseMatrix(pvApiCtx, piAddr, &iRows, &iCols, &iNbItem, &piNbItemRow, &piColPos);
151     if(sciErr.iErr)
152     {
153         printError(&sciErr, 0);
154         return 0;
155     }
156
157     //Do something with data
158     //convert %T -> %F and %F -> %T
159     iNewItem = (iRows * iCols) - iNbItem;
160     piNewRow = (int*)MALLOC(sizeof(int) * iRows);
161     piNewCol = (int*)MALLOC(sizeof(int) * iNewItem);
162
163     for(i = 0 ; i < iRows ; i++)
164     {
165         piNewRow[i] = iCols - piNbItemRow[i];
166         for(j = 0 ; j < iCols ; j++)
167         {
168             int iFind = 0;
169             for(k = 0 ; k < piNbItemRow[i] ; k++)
170             {
171                 if(piColPos[iCol + k] == (j + 1))
172                 {
173                     iFind = 1;
174                     break;
175                 }
176             }
177
178             if(iFind == 0)
179             {
180                 piNewCol[iNewCol++] = (j + 1);
181             }
182         }
183
184         iCol += piNbItemRow[i];
185     }
186
187     sciErr = createBooleanSparseMatrix(pvApiCtx, nbInputArgument(pvApiCtx) + 1, iRows, iCols, iNewItem, piNewRow, piNewCol);
188     if(sciErr.iErr)
189     {
190         printError(&sciErr, 0);
191         return 0;
192     }
193
194     AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
195     return 0;
196 }
197  ]]></programlisting>
198   </refsection>
199   <refsection>
200     <title>Scilab test script</title>
201     <programlisting role="code_scilab"><![CDATA[ 
202 a = sparse([%t, %f, %t ; %f, %t, %f ; %t, %f, %t]);
203 a_ref = sparse([%f, %t, %f ; %t, %f, %t ; %f, %t, %f]);
204
205 b = read_write_bsparse(a);
206 if or(b <> a_ref) then error("failed");end
207  ]]></programlisting>
208   </refsection>
209 </refentry>