Revert "Update of messages"
[scilab.git] / scilab / modules / api_scilab / help / en_US / 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 version="5.0-subset Scilab" xml:id="String_management_reading_API"
14           xml:lang="en" xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20
21     <refnamediv>
22         <refname>String reading (Scilab gateway)</refname>
23         <refpurpose>
24             How to read matrices of strings in a gateway.
25         </refpurpose>
26     </refnamediv>
27     <refsynopsisdiv>
28       <title>Calling Sequence</title>
29         <synopsis>int getMatrixOfString(int* _piAddress, int* _piRows, int* _piCols, int* _piLength, char** _pstStrings)</synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Parameters</title>
33         <variablelist>
34             <varlistentry>
35                 <term>_piAddress</term>
36                 <listitem>
37                     <para>
38                         Address of the Scilab variable.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>_piRows</term>
44                 <listitem>
45                     <para>
46                         Return number of rows.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>_piCols</term>
52                 <listitem>
53                     <para>
54                         Return number of columns.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>_piLength</term>
60                 <listitem>
61                     <para>
62                         Address of array of strings length (must be allocated size: _piRows * _piCols)
63                     </para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>_pstStrings</term>
68                 <listitem>
69                     <para>
70                         Address of array of char* (must be allocated size: _piRows * _piCols)
71                     </para>
72                 </listitem>
73             </varlistentry>
74         </variablelist>
75     </refsection>
76     <refsection>
77         <title>Description</title>
78         <para>This help describes how matrix of strings can be handled through the Scilab API.</para>
79     </refsection>
80     <refsection>
81         <!--File_gateway: SCI/modules/core/tests/unit_tests/string_reading_api.c-->
82         <!--File_scilab: SCI/modules/core/tests/unit_tests/string_reading_api.tst-->
83         <!--Lib_name: string_reading-->
84         <!--Func_list: read_string-->
85         <title>Gateway Source</title>
86         <programlisting role="code_gateway">
87             <![CDATA[
88 int read_string(char *fname,unsigned long fname_len)
89 {
90     int i,j;
91     int iLen        = 0;
92     int iRet        = 0;
93     //variable info
94     int iRows       = 0;
95     int iCols       = 0;
96     int* piAddr     = NULL;
97     int* piLen      = NULL;
98     char** pstData  = NULL;
99
100     //output variable
101     int iRowsOut    = 1;
102     int iColsOut    = 1;
103     char* pstOut    = NULL;
104
105     //check input and output arguments
106     CheckRhs(1,1);
107     CheckLhs(1,1);
108
109     //get variable address
110     iRet = getVarAddressFromPosition(1, &piAddr);
111     if(iRet)
112     {
113         return 1;
114     }
115
116     //check variable type
117     if(getVarType(piAddr) != sci_strings)
118     {
119         return 1;
120     }
121
122     //fisrt call to retrieve dimensions
123     iRet = getMatrixOfString(piAddr, &iRows, &iCols, NULL, NULL);
124     if(iRet)
125     {
126         return 1;
127     }
128
129     piLen = (int*)malloc(sizeof(int) * iRows * iCols);
130     //second call to retrieve length of each string
131     iRet = getMatrixOfString(piAddr, &iRows, &iCols, piLen, NULL);
132     if(iRet)
133     {
134         return 1;
135     }
136
137     pstData = (char**)malloc(sizeof(char*) * iRows * iCols);
138     for(i = 0 ; i < iRows * iCols ; i++)
139     {
140         pstData[i] = (char*)malloc(sizeof(char) * (piLen[i] + 1));//+ 1 for null termination
141     }
142     //third call to retrieve data
143     iRet = getMatrixOfString(piAddr, &iRows, &iCols, piLen, pstData);
144     if(iRet)
145     {
146         return 1;
147     }
148
149     //computer length of all strings
150     for(i = 0 ; i < iRows * iCols ; i++)
151     {
152         iLen += piLen[i];
153     }
154
155     //alloc output variable
156     pstOut = (char*)malloc(sizeof(char) * (iLen + iRows * iCols));
157     //initialize string to 0x00
158     memset(pstOut, 0x00, sizeof(char) * (iLen + iRows * iCols));
159
160     //concat input strings in output string
161     for(i = 0 ; i < iRows ; i++)
162     {
163         for(j = 0 ; j < iCols ; j++)
164         {
165             int iCurLen = strlen(pstOut);
166             if(iCurLen)
167             {
168                 strcat(pstOut, " ");
169             }
170             strcpy(pstOut + strlen(pstOut), pstData[j * iRows + i]);
171         }
172     }
173
174     //create new variable
175     iRet = createMatrixOfString(Rhs + 1, iRowsOut, iColsOut, &pstOut);
176     if(iRet)
177     {
178         return 1;
179     }
180
181     //free memory
182     free(piLen);
183     for(i = 0 ; i < iRows * iCols ; i++)
184     {
185         free(pstData[i]);
186     }
187     free(pstData);
188     free(pstOut);
189
190     LhsVar(1) = Rhs + 1;
191     return 0;
192 }
193             ]]>
194         </programlisting>
195     </refsection>
196
197     <refsection>
198         <title>Scilab test script</title>
199         <programlisting role="code_scilab">
200             <![CDATA[
201 a_ref = ["may the puffin be with you"];
202 a_ref = ["sample strings manipulation with gateway API"];
203 a = ["may", "the", "puffin"; "be","with","you"];
204 b = read_string(a);
205 if a_ref <> b then error("failed"), end
206             ]]>
207         </programlisting>
208     </refsection>
209 </refentry>