License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / api_scilab / includes / api_stack_string.h
1 /*
2  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
3  * Copyright (C) 2009 - DIGITEO - Antoine ELIAS
4  * Copyright (C) 2009 - DIGITEO - Allan CORNET
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  */
15
16 #ifndef __STACK_STRING_API__
17 #define __STACK_STRING_API__
18
19 #if !defined(__INTERNAL_API_SCILAB__)
20 #error Do not include api_stack_string.h. Include api_scilab.h instead.
21 #endif
22
23 #include <wchar.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 #include "dynlib_api_scilab.h"
30
31 /*****************************/
32 /*   string matrix functions   */
33 /*******************************/
34
35 /**
36  * Get strings variable data
37  * @param[in] _piAddress variable address
38  * @param[out] _piRows return number of rows
39  * @param[out] _piCols return number of columns
40  * @param[out] _piLength return strings lengths
41  * @param[out] _pstStrings return array of char
42  * @return if the operation succeeded (0) or not ( !0 )
43  */
44 SciErr getMatrixOfString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piLength, char** _pstStrings);
45
46 /**
47  * Get wide strings variable data
48  * @param[in] _piAddress variable address
49  * @param[out] _piRows return number of rows
50  * @param[out] _piCols return number of columns
51  * @param[out] _piwLength return strings length
52  * @param[out] _pwstStrings return array of wide char
53  * @return if the operation succeeded (0) or not ( !0 )
54  */
55 SciErr getMatrixOfWideString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piwLength, wchar_t** _pwstStrings);
56
57 /**
58  * Create strings variable data
59  * @param[in] _iVar variable number
60  * @param[in] _iRows number of rows
61  * @param[in] _iCols number of columns
62  * @param[in] _pstStrings array of strings ( null terminated )
63  * @return if the operation succeeded (0) or not ( !0 )
64  */
65 SciErr createMatrixOfString(void* _pvCtx, int _iVar, int _iRows, int _iCols, const char* const* _pstStrings);
66
67 /**
68 * Create wide strings variable data
69 * @param[in] _iVar variable number
70 * @param[in] _iRows Number of rows
71 * @param[in] _iCols Number of columns
72 * @param[in] _pwstStrings array of strings ( null terminated )
73 * @return if the operation succeeded (0) or not ( !0 )
74 */
75 SciErr createMatrixOfWideString(void* _pvCtx, int _iVar, int _iRows, int _iCols, const wchar_t* const* _pwstStrings);
76
77 /**
78  * Create strings variable data
79  * @param[in] _pstName variable name
80  * @param[in] _iRows Number of row
81  * @param[in] _iCols Number of column
82  * @param[in] _pstStrings array of strings ( null terminated )
83  * @return if the operation succeeded (0) or not ( !0 )
84  */
85 SciErr createNamedMatrixOfString(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const char* const* _pstStrings);
86
87 /**
88 * Create wide strings variable data
89 * @param[in] _pstName variable name
90 * @param[in] _iRows number of rows
91 * @param[in] _iCols number of columns
92 * @param[in] _pwstStrings array of wide strings ( null terminated )
93 * @return if the operation succeeded (0) or not ( !0 )
94 */
95 SciErr createNamedMatrixOfWideString(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, const wchar_t* const* _pwstStrings);
96
97 /**
98  * Get strings variable data
99  * @param[in] _pstName variable name
100  * @param[out] _piRows number of rows
101  * @param[out] _piCols number of columns
102  * @param[out] _piLength return strings lengths
103  * @param[in] _pstStrings array of strings ( null terminated )
104  * @return if the operation succeeded (0) or not ( !0 )
105  */
106 SciErr readNamedMatrixOfString(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piLength, char** _pstStrings);
107
108 /**
109 * Get wide strings variable data
110 * @param[in] _pstName variable name
111 * @param[out] _piRows number of rows
112 * @param[out] _piCols number of columns
113 * @param[out] _piwLength return strings length
114 * @param[in] _pstwStrings array of strings ( null terminated )
115 * @return if the operation succeeded (0) or not ( !0 )
116 */
117 SciErr readNamedMatrixOfWideString(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piwLength, wchar_t** _pwstStrings);
118
119 /*shortcut functions*/
120
121 /**
122  * check if the variable type is string
123  * @param[in] _piAddress variable address
124  * @return 1 for true and 0 for false
125  */
126 int isStringType(void* _pvCtx, int* _piAddress);
127
128 /**
129  * check if the variable type is string
130  * @param[in] _pstName variable name
131  * @return 1 for true and 0 for false
132  */
133 int isNamedStringType(void* _pvCtx, const char* _pstName);
134
135 /**
136  * Get single string variable data
137  * @param[in] _piAddress variable address
138  * @param[out] _pstData return allocated string pointer ( null terminated )
139  * @return if the operation succeeded (0) or not ( !0 )
140  */
141 int getAllocatedSingleString(void* _pvCtx, int* _piAddress, char** _pstData);
142
143 /**
144  * Get single wide string variable data
145  * @param[in] _piAddress variable address
146  * @param[out] _pwstData return allocated wide string pointer ( null terminated )
147  * @return if the operation succeeded (0) or not ( !0 )
148  */
149 int getAllocatedSingleWideString(void* _pvCtx, int* _piAddress, wchar_t** _pwstData);
150
151 /**
152  * Get strings variable data
153  * @param[in] _piAddress variable address
154  * @param[out] _piRows return number of rows
155  * @param[out] _piCols return number of columns
156  * @param[out] _pstData return allocated array of string pointer ( null terminated )
157  * @return if the operation succeeded (0) or not ( !0 )
158  */
159 int getAllocatedMatrixOfString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, char*** _pstData);
160
161 /**
162  * Get wide strings variable data
163  * @param[in] _piAddress variable address
164  * @param[out] _piRows return number of rows
165  * @param[out] _piCols return number of columns
166  * @param[out] _pwstData return allocated array of wide string pointer ( null terminated )
167  * @return if the operation succeeded (0) or not ( !0 )
168  */
169 int getAllocatedMatrixOfWideString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, wchar_t*** _pwstData);
170
171
172 /**
173  * Get single named string variable data
174  * @param[in] _pstName variable name
175  * @param[out] _pstData return allocated string pointer ( null terminated )
176  * @return if the operation succeeded (0) or not ( !0 )
177  */
178 int getAllocatedNamedSingleString(void* _pvCtx, const char* _pstName, char** _pstData);
179
180 /**
181  * Get single named string variable data
182  * @param[in] _pstName variable name
183  * @param[out] _pwstData return allocated string pointer ( null terminated )
184  * @return if the operation succeeded (0) or not ( !0 )
185  */
186 int getAllocatedNamedSingleWideString(void* _pvCtx, const char* _pstName, wchar_t** _pwstData);
187
188 /**
189  * Get named strings variable data
190  * @param[in] _pstName variable name
191  * @param[out] _piRows number of rows
192  * @param[out] _piCols number of columns
193  * @param[out] _pstData return allocated array of string pointer ( null terminated )
194  * @return if the operation succeeded (0) or not ( !0 )
195  */
196 int getAllocatedNamedMatrixOfString(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, char*** _pstData);
197
198 /**
199  * Get named wide strings variable data
200  * @param[in] _pstName variable name
201  * @param[out] _piRows number of rows
202  * @param[out] _piCols number of columns
203  * @param[out] _pwstData return allocated array of wide string pointer ( null terminated )
204  * @return if the operation succeeded (0) or not ( !0 )
205  */
206 int getAllocatedNamedMatrixOfWideString(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, wchar_t*** _pwstData);
207
208 /**
209  * Create single string variable data
210  * @param[in] _iVar variable number
211  * @param[in] _pstStrings string ( null terminated )
212  * @return if the operation succeeded (0) or not ( !0 )
213  */
214 int createSingleString(void* _pvCtx, int _iVar, const char* _pstStrings);
215
216 /**
217  * Create single string variable data
218  * @param[in] _iVar variable number
219  * @param[in] _iLen string length to reserve space in stack
220  * @param[out] pointer on the new single string
221  * @return if the operation succeeded (0) or not ( !0 )
222  */
223 int allocSingleString(void* _pvCtx, int _iVar, int _iLen, const char** _pstStrings);
224
225 /**
226  * Create single wide string variable data
227  * @param[in] _iVar variable number
228  * @param[in] _pwstStrings wide string ( null terminated )
229  * @return if the operation succeeded (0) or not ( !0 )
230  */
231 int createSingleWideString(void* _pvCtx, int _iVar, const wchar_t* _pwstStrings);
232
233 /**
234  * Create named single string variable data
235  * @param[in] _pstName variable name
236  * @param[in] _pstStrings string ( null terminated )
237  * @return if the operation succeeded (0) or not ( !0 )
238  */
239 int createNamedSingleString(void* _pvCtx, const char* _pstName, const char* _pstStrings);
240
241 /**
242  * Create named single wide string variable data
243  * @param[in] _pstName variable name
244  * @param[in] _pwstStrings wide string ( null terminated )
245  * @return if the operation succeeded (0) or not ( !0 )
246  */
247 int createNamedSingleWideString(void* _pvCtx, const char* _pstName, const wchar_t* _pwstStrings);
248
249 /**
250  * free data allocated by shortcut functions ( named or not )
251  * @param[in] _pstData string data
252  */
253 void freeAllocatedSingleString(char* _pstData);
254
255 /**
256  * free data allocated by shortcut functions ( named or not )
257  * @param[in] _pwstData wide string data
258  */
259 void freeAllocatedSingleWideString(wchar_t* _pwstData);
260
261 /**
262  * free data allocated by shortcut functions ( named or not )
263  * @param[in] _iRows number of rows
264  * @param[in] _iCols number of columns
265  * @param[in] _pstData matrix of string data
266  */
267 void freeAllocatedMatrixOfString(int _iRows, int _iCols, char** _pstData);
268
269 /**
270  * free data allocated by shortcut functions ( named or not )
271  * @param[in] _iRows number of rows
272  * @param[in] _iCols number of columns
273  * @param[in] _pwstData matrix of wide string data
274  */
275 void freeAllocatedMatrixOfWideString(int _iRows, int _iCols, wchar_t** _pwstData);
276
277 #ifdef __cplusplus
278 }
279 #endif
280
281 #endif /* __STACK_STRING_API__ */