License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / api_scilab / help / en_US / K_struct.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) 2015  - Scilab Enterprises - Antoine ELIAS
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 <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" xmlns:scilab="http://www.scilab.org" xml:id="api_struct" xml:lang="en">
17     <refnamediv>
18         <refname>API struct functions</refname>
19         <para>This page lists all the functions to manipulate functions to manipulate Struct objects.</para>
20         <para></para>
21     </refnamediv>
22     <refsynopsisdiv>
23         <refsection id="api_struct_scilab_createStructMatrix">
24             <literal>
25                 <link linkend="api_types_scilabVar">
26                     <command>scilabVar</command>
27                 </link>
28                 <varname>scilab_createStructMatrix</varname>(
29                 <link linkend="api_types_scilabEnv">
30                     <command>scilabEnv</command>
31                 </link>
32                 env, int dim, const int* dims)
33             </literal>
34             <para>
35                 Create a struct matrix with <varname>dim</varname> dimensions (<varname>dims</varname>[0], <varname>dims</varname>[1], ..., <varname>dims</varname>[<varname>dim</varname>-1]).
36             </para>
37         </refsection>
38         <refsection id="api_struct_scilab_createStructMatrix2d">
39             <literal>
40                 <link linkend="api_types_scilabVar">
41                     <command>scilabVar</command>
42                 </link>
43                 <varname>scilab_createStructMatrix2d</varname>(
44                 <link linkend="api_types_scilabEnv">
45                     <command>scilabEnv</command>
46                 </link>
47                 env, int row, int col)
48             </literal>
49             <para>
50                 Create an struct matrix with 2 dimensions (<varname>row</varname>, <varname>col</varname>).
51             </para>
52         </refsection>
53         <refsection id="api_struct_scilab_createStruct">
54             <literal>
55                 <link linkend="api_types_scilabVar">
56                     <command>scilabVar</command>
57                 </link>
58                 <varname>scilab_createStruct</varname>(
59                 <link linkend="api_types_scilabEnv">
60                     <command>scilabEnv</command>
61                 </link>
62                 env)
63             </literal>
64             <para>Create a scalar struct.</para>
65         </refsection>
66         <refsection id="api_struct_scilab_addFields">
67             <literal>
68                 <link linkend="api_types_scilabStatus">
69                     <command>scilabStatus</command>
70                 </link>
71                 <varname>scilab_addFields</varname>(
72                 <link linkend="api_types_scilabEnv">
73                     <command>scilabEnv</command>
74                 </link>
75                 env, 
76                 <link linkend="api_types_scilabVar">
77                     <command>scilabVar</command>
78                 </link>
79                 var, int count, const wchar_t** fields)
80             </literal>
81             <para>
82                 Add <varname>count</varname> fields <varname>fields</varname> in struct <varname>var</varname>.
83             </para>
84         </refsection>
85         <refsection id="api_struct_scilab_addField">
86             <literal>
87                 <link linkend="api_types_scilabStatus">
88                     <command>scilabStatus</command>
89                 </link>
90                 <varname>scilab_addField</varname>(
91                 <link linkend="api_types_scilabEnv">
92                     <command>scilabEnv</command>
93                 </link>
94                 env, 
95                 <link linkend="api_types_scilabVar">
96                     <command>scilabVar</command>
97                 </link>
98                 var, const wchar_t* field)
99             </literal>
100             <para>
101                 Add field <varname>field</varname> in struct <varname>var</varname>.
102             </para>
103         </refsection>
104         <refsection id="api_struct_scilab_getFields">
105             <literal>
106                 int <varname>scilab_getFields</varname>(
107                 <link linkend="api_types_scilabEnv">
108                     <command>scilabEnv</command>
109                 </link>
110                 env, 
111                 <link linkend="api_types_scilabVar">
112                     <command>scilabVar</command>
113                 </link>
114                 var, wchar_t*** fields)
115             </literal>
116             <para>
117                 Get field names <varname>fields</varname> from struct <varname>var</varname> and returns count of fields.
118             </para>
119         </refsection>
120         <refsection id="api_struct_scilab_getStructMatrixData">
121             <literal>
122                 <link linkend="api_types_scilabVar">
123                     <command>scilabVar</command>
124                 </link>
125                 <varname>scilab_getStructMatrixData</varname>(
126                 <link linkend="api_types_scilabEnv">
127                     <command>scilabEnv</command>
128                 </link>
129                 env, const wchar_t* field, const int* dims)
130             </literal>
131             <para>
132                 Get field value at position (<varname>index</varname>[0], <varname>index</varname>[1], ..., <varname>index</varname>[dims-1]) from <varname>var</varname>.
133             </para>
134         </refsection>
135         <refsection id="api_struct_scilab_getStructMatrixData2d">
136             <literal>
137                 <link linkend="api_types_scilabVar">
138                     <command>scilabVar</command>
139                 </link>
140                 <varname>scilab_getStructMatrixData2d</varname>(
141                 <link linkend="api_types_scilabEnv">
142                     <command>scilabEnv</command>
143                 </link>
144                 env, const wchar_t* field, int row, int col)
145             </literal>
146             <para>
147                 Get field value at position (<varname>row</varname>, <varname>col</varname>) from <varname>var</varname>.
148             </para>
149         </refsection>
150         <refsection id="api_struct_scilab_setStructMatrixData">
151             <literal>
152                 <link linkend="api_types_scilabStatus">
153                     <command>scilabStatus</command>
154                 </link>
155                 <varname>scilab_setStructMatrixData</varname>(
156                 <link linkend="api_types_scilabEnv">
157                     <command>scilabEnv</command>
158                 </link>
159                 env, 
160                 <link linkend="api_types_scilabVar">
161                     <command>scilabVar</command>
162                 </link>
163                 var, const wchar_t* field, const int* index, 
164                 <link linkend="api_types_scilabVar">
165                     <command>scilabVar</command>
166                 </link>
167                 data)
168             </literal>
169             <para>
170                 Set field value at position (<varname>index</varname>[0], <varname>index</varname>[1], ..., <varname>index</varname>[dims-1]) in <varname>var</varname>.
171             </para>
172         </refsection>
173         <refsection id="api_struct_scilab_setStructMatrixData2d">
174             <literal>
175                 <link linkend="api_types_scilabStatus">
176                     <command>scilabStatus</command>
177                 </link>
178                 <varname>scilab_setStructMatrixData2d</varname>(
179                 <link linkend="api_types_scilabEnv">
180                     <command>scilabEnv</command>
181                 </link>
182                 env, 
183                 <link linkend="api_types_scilabVar">
184                     <command>scilabVar</command>
185                 </link>
186                 var, const wchar_t* field, int row, int col, 
187                 <link linkend="api_types_scilabVar">
188                     <command>scilabVar</command>
189                 </link>
190                 data)
191             </literal>
192             <para>
193                 Set field value at position (<varname>row</varname>, <varname>col</varname>) in <varname>var</varname>.
194             </para>
195         </refsection>
196     </refsynopsisdiv>
197     <refsection>
198         <title>Examples</title>
199         <programlisting role="code_gateway">
200             <![CDATA[
201 #include <ctype.h>
202 #include "api_scilab.h"
203 #include "Scierror.h"
204 #include "localization.h"
205 #include "sciprint.h"
206 #include "sci_malloc.h"
207 #include "os_string.h"
208
209 const char fname[] = "struct_test";
210
211 int sci_struct_test(scilabEnv env, int nin, scilabVar* in, int nopt, scilabOpt opt, int nout, scilabVar* out)
212 {
213     int i = 0;
214     //input
215     scilabVar in1 = NULL;
216     int size1 = 0;
217     wchar_t** fields = NULL;
218     scilabVar in2 = NULL;
219     int size2 = 0;
220     //output
221     scilabVar out1 = NULL;
222
223     //goal is to take string vector and list from intput to
224     //create a struct with fields names from string and
225     //fields data from list.
226
227     if (nin != 2)
228     {
229         Scierror(999, _("%s: Wrong number of input arguments: %d expected.\n"), fname, 2);
230         return STATUS_ERROR;
231     }
232
233     if (nout != 1)
234     {
235         Scierror(999, _("%s: Wrong number of output arguments: %d expected.\n"), fname, 1);
236         return STATUS_ERROR;
237     }
238
239     //in1
240     in1 = in[0];
241     if (scilab_isString(env, in1) == 0 || scilab_isVector(env, in1) == 0)
242     {
243         Scierror(999, _("%s: Wrong type for input argument #%d: A string vector expected.\n"), fname, 1);
244         return STATUS_ERROR;
245     }
246
247     size1 = scilab_getSize(env, in1);
248     scilab_getStringArray(env, in1, &fields);
249
250     //in2
251     in2 = in[1];
252     if (scilab_isList(env, in2) == 0)
253     {
254         Scierror(999, _("%s: Wrong type for input argument #%d: A list expected.\n"), fname, 2);
255         return STATUS_ERROR;
256     }
257
258     size2 = scilab_getSize(env, in2);
259
260     if (size1 != size2)
261     {
262         Scierror(999, _("%s: Wrong type for input argument #%d: arg1 and arg2 must have same size.\n"), fname);
263         return STATUS_ERROR;
264     }
265
266     out1 = scilab_createStruct(env);
267
268     for (i = 0; i < size1; ++i)
269     {
270         scilab_addField(env, out1, fields[i]);
271         scilab_setStruct2dData(env, out1, fields[i], 0, 0, scilab_getListItem(env, in2, i));
272     }
273
274     out[0] = out1;
275     return STATUS_OK;
276 }
277             ]]>
278         </programlisting>
279     </refsection>
280     <refsection>
281         <title>Scilab test script</title>
282         <programlisting role="code_scilab">
283             <![CDATA[
284 mkdir(pathconvert(TMPDIR+"/api_c/"));
285 cd(pathconvert(TMPDIR+"/api_c/"));
286 copyfile(SCI+"/modules/api_scilab/tests/unit_tests/api_c/struct_test.c",pathconvert(TMPDIR+"/api_c/struct_test.c",%F));
287
288 ilib_build("libstruct",["struct_test","sci_struct_test", "csci6"],"struct_test.c",[],"","","");
289 exec("loader.sce");
290
291 fields = ["double","string","boolean","poly","list","cell"];
292 data = list(1, "2", %t, %s, list(1,2,3), {1,2;3,4});
293 t = struct_test(fields, data);
294
295 assert_checkequal(typeof(t), "st");
296 assert_checkequal(t.double, 1);
297 assert_checkequal(t.string, "2");
298 assert_checkequal(t.boolean, %t);
299 assert_checkequal(t.poly, %s);
300 assert_checkequal(t.list, list(1,2,3));
301 assert_checkequal(t.cell, {1,2;3,4});
302             ]]>
303         </programlisting>
304     </refsection>
305 </refentry>