update api_scilab documention with changes on pvApiCtx
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / sparse_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="Sparse_management_reading_API" xml:lang="en">
14   <refnamediv>
15     <refname>Sparse matrix reading (Scilab gateway)</refname>
16     <refpurpose>
17       How to read sparse matrices in a gateway.
18     </refpurpose>
19   </refnamediv>
20   <refsynopsisdiv>
21     <title>Calling Sequence</title>
22     <para>Input argument profile:</para>
23     <synopsis>SciErr getSparseMatrix(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piNbItem, int** _piNbItemRow, int** _piColPos, double** _pdblReal)</synopsis>
24     <synopsis>SciErr getComplexSparseMatrix(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piNbItem, int** _piNbItemRow, int** _piColPos, double** _pdblReal, double** _pdblImg)</synopsis>
25     <para>Named variable profile:</para>
26     <synopsis>SciErr readNamedSparseMatrix(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piNbItem, int* _piNbItemRow, int* _piColPos, double* _pdblReal)</synopsis>
27     <synopsis>SciErr readNamedComplexSparseMatrix(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piNbItem, int* _piNbItemRow, int* _piColPos, double* _pdblReal, double* _pdblImg)</synopsis>
28   </refsynopsisdiv>
29   <refsection>
30     <title>Arguments</title>
31     <variablelist>
32       <varlistentry>
33         <term>_pvCtx</term>
34         <listitem>
35           <para>
36             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
37           </para>
38         </listitem>
39       </varlistentry>
40       <varlistentry>
41         <term>_piAddress</term>
42         <listitem>
43           <para>
44             Address of the Scilab variable.
45           </para>
46         </listitem>
47       </varlistentry>
48       <varlistentry>
49         <term>_pstName</term>
50         <listitem>
51           <para>
52             Name of the variable for "named" functions.
53           </para>
54         </listitem>
55       </varlistentry>
56       <varlistentry>
57         <term>_piRows</term>
58         <listitem>
59           <para>
60             Return number of rows.
61           </para>
62         </listitem>
63       </varlistentry>
64       <varlistentry>
65         <term>_piCols</term>
66         <listitem>
67           <para>
68             Return number of columns.
69           </para>
70         </listitem>
71       </varlistentry>
72       <varlistentry>
73         <term>_piNbItem</term>
74         <listitem>
75           <para>
76             Return number of non zero value.
77           </para>
78         </listitem>
79       </varlistentry>
80       <varlistentry>
81         <term>_piNbItemRow</term>
82         <listitem>
83           <para>
84             Return number of item in each rows (size: _iRows).
85           </para>
86         </listitem>
87       </varlistentry>
88       <varlistentry>
89         <term>_piColPos</term>
90         <listitem>
91           <para>
92             Return column position for each item (size: _iNbItem).
93           </para>
94         </listitem>
95       </varlistentry>
96       <varlistentry>
97         <term>_pdblReal</term>
98         <listitem>
99           <para>
100             Return address of real data array (size: _iCols * _iRows)
101             For "Named" function, _pdblReal must be allocated before calling function.
102           </para>
103         </listitem>
104       </varlistentry>
105       <varlistentry>
106         <term>_pdblImg</term>
107         <listitem>
108           <para>
109             Return address of imaginary data array (size: _iCols * _iRows)
110             For "Named" function, _pdblImg must be allocated before calling function.
111           </para>
112         </listitem>
113       </varlistentry>
114       <varlistentry>
115         <term>SciErr</term>
116         <listitem>
117           <para>
118             Error structure where is stored errors messages history and first error number.
119           </para>
120         </listitem>
121       </varlistentry>
122     </variablelist>
123   </refsection>
124   <refsection>
125     <title>Description</title>
126     <para>This help describes how sparse matrix can be handled through the Scilab API.</para>
127   </refsection>
128   <refsection>
129     <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/sparse_reading_api.c-->
130     <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/sparse_reading_api.tst-->
131     <!--Lib_name: sparse_reading-->
132     <!--Func_list: read_sparse-->
133     <title>Gateway Source</title>
134     <programlisting role="code_gateway"><![CDATA[ 
135 #include "api_scilab.h"
136 int read_sparse(char *fname,unsigned long fname_len)
137 {
138         SciErr sciErr;
139         int i,j,k;
140         int* piAddr                     = NULL;
141         int iRows                       = 0;
142         int iCols                       = 0;
143         int iNbItem                     = 0;
144         int* piNbItemRow        = NULL;
145         int* piColPos           = NULL;
146         double* pdblReal        = NULL;
147         double* pdblImg         = NULL;
148
149     CheckInputArgument(pvApiCtx, 1, 1);
150
151         sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
152         if(sciErr.iErr)
153         {
154                 printError(&sciErr, 0);
155                 return 0;
156         }
157
158         if(isVarComplex(pvApiCtx, piAddr))
159         {
160                 sciErr = getComplexSparseMatrix(pvApiCtx, piAddr, &iRows, &iCols, &iNbItem, &piNbItemRow, &piColPos, &pdblReal, &pdblImg);
161         }
162         else
163         {
164                 sciErr = getSparseMatrix(pvApiCtx, piAddr, &iRows, &iCols, &iNbItem, &piNbItemRow, &piColPos, &pdblReal);
165         }
166
167         if(sciErr.iErr)
168         {
169                 printError(&sciErr, 0);
170                 return 0;
171         }
172
173         sciprint("Sparse %d item(s)\n", iNbItem);
174         k = 0;
175
176         for(i = 0 ; i < iRows ; i++)
177         {
178                 for(j = 0 ; j < piNbItemRow[i] ; j++)
179                 {
180                         sciprint("(%d,%d) = %f", i+1, piColPos[k], pdblReal[k]);
181                         if(isVarComplex(pvApiCtx, piAddr))
182                         {
183                                 sciprint(" %+fi", pdblImg[k]);
184                         }
185
186                         sciprint("\n");
187                         k++;
188                 }
189         }
190
191         //assign allocated variables to Lhs position
192         AssignOutputVariable(pvApiCtx, 1) = 0;
193         return 0;
194 }
195  ]]></programlisting>
196   </refsection>
197   <refsection>
198     <title>Scilab test script</title>
199     <programlisting role="code_scilab"><![CDATA[ 
200 sp=sparse([1,2;4,5;3,10],[1 + 2*%i,2 - 3*%i,-3 + 4*%i]);
201 read_sparse(sp);
202  ]]></programlisting>
203   </refsection>
204 </refentry>