Fix a typo. fisrt => first
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / string_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="String_management_reading_API" xml:lang="en">
14     <refnamediv>
15         <refname>String reading (Scilab gateway)</refname>
16         <refpurpose>
17             How to read matrices of strings in a gateway.
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <para>Input argument profile:</para>
23         <synopsis>SciErr getMatrixOfString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piLength, char** _pstStrings)</synopsis>
24         <synopsis>SciErr getMatrixOfWideString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piLength, wchar_t** _pwstStrings)</synopsis>
25         <para>Named variable profile:</para>
26         <synopsis>SciErr createNamedMatrixOfString(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, char** _pstStrings)</synopsis>
27         <synopsis>SciErr createNamedMatrixOfWideString(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, wchar_t** _pwstStrings)</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>_piLength</term>
74                 <listitem>
75                     <para>
76                         Address of array of strings length (must be allocated size: _piRows * _piCols)
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>_pstStrings</term>
82                 <listitem>
83                     <para>
84                         Address of array of char* (must be allocated size: _piRows * _piCols)
85                     </para>
86                 </listitem>
87             </varlistentry>
88             <varlistentry>
89                 <term>_pwstStrings</term>
90                 <listitem>
91                     <para>
92                         Address of array of wchar_t* (must be allocated size: _piRows * _piCols)
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 matrix of strings can be handled through the Scilab API.</para>
109     </refsection>
110     <refsection>
111         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/string_reading_api.c-->
112         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/string_reading_api.tst-->
113         <!--Lib_name: string_reading-->
114         <!--Func_list: read_string-->
115         <title>Gateway Source</title>
116         <programlisting role="code_gateway"><![CDATA[ 
117 #include "api_scilab.h"
118 int read_string(char *fname,unsigned long fname_len)
119 {
120         SciErr sciErr;
121         int i,j;
122         int iLen                = 0;
123         //variable info
124         int iRows               = 0;
125         int iCols               = 0;
126         int* piAddr             = NULL;
127         int* piLen              = NULL;
128         char** pstData  = NULL;
129         //output variable
130         int iRowsOut    = 1;
131         int iColsOut    = 1;
132         char* pstOut    = NULL;
133         //check input and output arguments
134
135     CheckInputArgument(pvApiCtx, 1, 1);
136     CheckOutputArgument(pvApiCtx, 1, 1);
137
138         //get variable address
139         sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
140         if(sciErr.iErr)
141         {
142                 printError(&sciErr, 0);
143                 return 0;
144         }
145
146         //first call to retrieve dimensions
147         sciErr = getMatrixOfString(pvApiCtx, piAddr, &iRows, &iCols, NULL, NULL);
148         if(sciErr.iErr)
149         {
150                 printError(&sciErr, 0);
151                 return 0;
152         }
153
154         piLen = (int*)malloc(sizeof(int) * iRows * iCols);
155
156         //second call to retrieve length of each string
157         sciErr = getMatrixOfString(pvApiCtx, piAddr, &iRows, &iCols, piLen, NULL);
158         if(sciErr.iErr)
159         {
160                 printError(&sciErr, 0);
161                 return 0;
162         }
163
164         pstData = (char**)malloc(sizeof(char*) * iRows * iCols);
165         for(i = 0 ; i < iRows * iCols ; i++)
166         {
167                 pstData[i] = (char*)malloc(sizeof(char) * (piLen[i] + 1));//+ 1 for null termination
168         }
169
170         //third call to retrieve data
171         sciErr = getMatrixOfString(pvApiCtx, piAddr, &iRows, &iCols, piLen, pstData);
172         if(sciErr.iErr)
173         {
174                 printError(&sciErr, 0);
175                 return 0;
176         }
177
178         //computer length of all strings
179         for(i = 0 ; i < iRows * iCols ; i++)
180         {
181                 iLen += piLen[i];
182         }
183
184         //alloc output variable
185         pstOut = (char*)malloc(sizeof(char) * (iLen + iRows * iCols));
186         //initialize string to 0x00
187         memset(pstOut, 0x00, sizeof(char) * (iLen + iRows * iCols));
188
189         //concat input strings in output string
190         for(i = 0 ; i < iRows ; i++)
191         {
192                 for(j = 0 ; j < iCols ; j++)
193                 {
194                         int iCurLen = strlen(pstOut);
195                         if(iCurLen)
196                         {
197                                 strcat(pstOut, " ");
198                         }
199                         strcpy(pstOut + strlen(pstOut), pstData[j * iRows + i]);
200                 }
201         }
202
203         //create new variable
204         sciErr = createMatrixOfString(pvApiCtx, nbInputArgument(pvApiCtx) + 1, iRowsOut, iColsOut, &pstOut);
205         if(sciErr.iErr)
206         {
207                 printError(&sciErr, 0);
208                 return 0;
209         }
210
211         //free memory
212         free(piLen);
213
214         for(i = 0 ; i < iRows * iCols ; i++)
215         {
216                 free(pstData[i]);
217         }
218
219         free(pstData);
220         free(pstOut);
221         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
222         return 0;
223 }
224  ]]></programlisting>
225     </refsection>
226     <refsection>
227         <title>Scilab test script</title>
228         <programlisting role="code_scilab"><![CDATA[ 
229 a_ref = ["may the puffin be with you"];
230 a = ["may", "the", "puffin"; "be","with","you"];
231 b = read_string(a);
232 if a_ref <> b then error("failed"), end
233  ]]></programlisting>
234     </refsection>
235 </refentry>