d5fe0efdac20d2deba2bc4965b316d4c7fa7bece
[scilab.git] / scilab / modules / api_scilab / help / en_US / CC_common.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_common" xml:lang="en">
17     <refnamediv>
18         <refname>API common functions</refname>
19         <para>This page lists all the functions to get information about Scilab native objects.</para>
20     </refnamediv>
21     <refsection id="api_common_scilab_getVar">
22         <literal>
23             <link linkend="api_types_scilabVar">
24                 <command>scilabVar</command>
25             </link>
26             <varname>scilab_getVar</varname>(const wchar_t* name)
27         </literal>
28         <para>
29             Return variable called <varname>name</varname>, NULL if variable does not exist.
30         </para>
31     </refsection>
32     <refsection id="api_common_scilab_getClone">
33         <literal>
34             <link linkend="api_types_scilabVar">
35                 <command>scilabVar</command>
36             </link>
37             <varname>scilab_getClone</varname>(
38             <link linkend="api_types_scilabEnv">
39                 <command>scilabEnv</command>
40             </link>
41             env,
42             <link linkend="api_types_scilabVar">
43                 <command>scilabVar</command>
44             </link>
45             var)
46         </literal>
47         <para>
48             Return a copie of <varname>var</varname>.
49         </para>
50     </refsection>
51     <refsection id="api_common_scilab_getType">
52         <literal>
53             int <varname>scilab_getType</varname>(
54             <link linkend="api_types_scilabEnv">
55                 <command>scilabEnv</command>
56             </link>
57             env,
58             <link linkend="api_types_scilabVar">
59                 <command>scilabVar</command>
60             </link>
61             var)
62         </literal>
63         <para>
64             Get type of <varname>var</varname>. see
65             <link linkend="sci_types">
66                 <command>types</command>
67             </link>
68             help page.
69         </para>
70     </refsection>
71     <refsection>
72         <literallayout>
73             int <varname>scilab_isDouble</varname>(
74             <link linkend="api_types_scilabEnv">
75                 <command>scilabEnv</command>
76             </link>
77             env,
78             <link linkend="api_types_scilabVar">
79                 <command>scilabVar</command>
80             </link>
81             var)
82             int <varname>scilab_isBoolean</varname>(
83             <link linkend="api_types_scilabEnv">
84                 <command>scilabEnv</command>
85             </link>
86             env,
87             <link linkend="api_types_scilabVar">
88                 <command>scilabVar</command>
89             </link>
90             var)
91             int <varname>scilab_isString</varname>(
92             <link linkend="api_types_scilabEnv">
93                 <command>scilabEnv</command>
94             </link>
95             env,
96             <link linkend="api_types_scilabVar">
97                 <command>scilabVar</command>
98             </link>
99             var)
100             int <varname>scilab_isInt</varname>(
101             <link linkend="api_types_scilabEnv">
102                 <command>scilabEnv</command>
103             </link>
104             env,
105             <link linkend="api_types_scilabVar">
106                 <command>scilabVar</command>
107             </link>
108             var)
109             int <varname>scilab_isPoly</varname>(
110             <link linkend="api_types_scilabEnv">
111                 <command>scilabEnv</command>
112             </link>
113             env,
114             <link linkend="api_types_scilabVar">
115                 <command>scilabVar</command>
116             </link>
117             var)
118             int <varname>scilab_isList</varname>(
119             <link linkend="api_types_scilabEnv">
120                 <command>scilabEnv</command>
121             </link>
122             env,
123             <link linkend="api_types_scilabVar">
124                 <command>scilabVar</command>
125             </link>
126             var)
127             int <varname>scilab_isTList</varname>(
128             <link linkend="api_types_scilabEnv">
129                 <command>scilabEnv</command>
130             </link>
131             env,
132             <link linkend="api_types_scilabVar">
133                 <command>scilabVar</command>
134             </link>
135             var)
136             int <varname>scilab_isMList</varname>(
137             <link linkend="api_types_scilabEnv">
138                 <command>scilabEnv</command>
139             </link>
140             env,
141             <link linkend="api_types_scilabVar">
142                 <command>scilabVar</command>
143             </link>
144             var)
145             int <varname>scilab_isHandle</varname>(
146             <link linkend="api_types_scilabEnv">
147                 <command>scilabEnv</command>
148             </link>
149             env,
150             <link linkend="api_types_scilabVar">
151                 <command>scilabVar</command>
152             </link>
153             var)
154             int <varname>scilab_isStruct</varname>(
155             <link linkend="api_types_scilabEnv">
156                 <command>scilabEnv</command>
157             </link>
158             env,
159             <link linkend="api_types_scilabVar">
160                 <command>scilabVar</command>
161             </link>
162             var)
163             int <varname>scilab_isCell</varname>(
164             <link linkend="api_types_scilabEnv">
165                 <command>scilabEnv</command>
166             </link>
167             env,
168             <link linkend="api_types_scilabVar">
169                 <command>scilabVar</command>
170             </link>
171             var)
172             int <varname>scilab_isPointer</varname>(
173             <link linkend="api_types_scilabEnv">
174                 <command>scilabEnv</command>
175             </link>
176             env,
177             <link linkend="api_types_scilabVar">
178                 <command>scilabVar</command>
179             </link>
180             var)
181         </literallayout>
182         <para>
183             Return 1 if variable <varname>var</varname> has the right type.
184         </para>
185     </refsection>
186     <refsection id="api_common_scilab_isComplex">
187         <literal>
188             int <varname>scilab_isComplex</varname>(
189             <link linkend="api_types_scilabEnv">
190                 <command>scilabEnv</command>
191             </link>
192             env,
193             <link linkend="api_types_scilabVar">
194                 <command>scilabVar</command>
195             </link>
196             var)
197         </literal>
198         <para>
199             Return 1 if variable <varname>var</varname> is complex.
200         </para>
201     </refsection>
202     <refsection id="api_common_scilab_getDim">
203         <literal>
204             int <varname>scilab_getDim</varname>(
205             <link linkend="api_types_scilabEnv">
206                 <command>scilabEnv</command>
207             </link>
208             env,
209             <link linkend="api_types_scilabVar">
210                 <command>scilabVar</command>
211             </link>
212             var)
213         </literal>
214         <para>
215             Return the number of dimension of <varname>var</varname>. Note that scalar variables are 2d matrix of dimension (1, 1)
216         </para>
217     </refsection>
218     <refsection id="api_common_scilab_getDim2d">
219         <literal>
220             int <varname>scilab_getDim2d</varname>(
221             <link linkend="api_types_scilabEnv">
222                 <command>scilabEnv</command>
223             </link>
224             env,
225             <link linkend="api_types_scilabVar">
226                 <command>scilabVar</command>
227             </link>
228             var, int* row, int* col)
229         </literal>
230         <para>
231             Return dimensions of a 2d variable <varname>var</varname> in <varname>row</varname> and <varname>col</varname>.
232         </para>
233     </refsection>
234     <refsection id="api_common_scilab_getDimArray">
235         <literal>
236             int <varname>scilab_getDimArray</varname>(
237             <link linkend="api_types_scilabEnv">
238                 <command>scilabEnv</command>
239             </link>
240             env,
241             <link linkend="api_types_scilabVar">
242                 <command>scilabVar</command>
243             </link>
244             var, const int** dims)
245         </literal>
246         <para>
247             Return pointer on array of dimensions of a variable <varname>var</varname> in <varname>dims</varname>.
248         </para>
249     </refsection>
250     <refsection id="api_common_scilab_getSize">
251         <literal>
252             int <varname>scilab_getSize</varname>(
253             <link linkend="api_types_scilabEnv">
254                 <command>scilabEnv</command>
255             </link>
256             env,
257             <link linkend="api_types_scilabVar">
258                 <command>scilabVar</command>
259             </link>
260             var)
261         </literal>
262         <para>
263             Return size of variable <varname>var</varname>.
264         </para>
265         <para>For matrix type is the result of product of dimension and for others like list is the item count.</para>
266     </refsection>
267     <refsection id="api_common_scilab_isEmpty">
268         <literal>
269             int <varname>scilab_isEmpty</varname>(
270             <link linkend="api_types_scilabEnv">
271                 <command>scilabEnv</command>
272             </link>
273             env,
274             <link linkend="api_types_scilabVar">
275                 <command>scilabVar</command>
276             </link>
277             var)
278         </literal>
279         <para>Return 1 for empty matrix and empty list.</para>
280     </refsection>
281     <refsection id="api_common_scilab_isMatrix2d">
282         <literal>
283             int <varname>scilab_isMatrix2d</varname>(
284             <link linkend="api_types_scilabEnv">
285                 <command>scilabEnv</command>
286             </link>
287             env,
288             <link linkend="api_types_scilabVar">
289                 <command>scilabVar</command>
290             </link>
291             var)
292         </literal>
293         <para>Return 1 for matrix with 2 dimensions and scalar.</para>
294     </refsection>
295     <refsection id="api_common_scilab_isScalar">
296         <literal>
297             int <varname>scilab_isScalar</varname>(
298             <link linkend="api_types_scilabEnv">
299                 <command>scilabEnv</command>
300             </link>
301             env,
302             <link linkend="api_types_scilabVar">
303                 <command>scilabVar</command>
304             </link>
305             var)
306         </literal>
307         <para>Return 1 for scalar value.</para>
308     </refsection>
309     <refsection id="api_common_scilab_isSquare">
310         <literal>
311             int <varname>scilab_isSquare</varname>(
312             <link linkend="api_types_scilabEnv">
313                 <command>scilabEnv</command>
314             </link>
315             env,
316             <link linkend="api_types_scilabVar">
317                 <command>scilabVar</command>
318             </link>
319             var)
320         </literal>
321         <para>Return 1 for matrix with 2 dimensions and dimensions have the same size.</para>
322     </refsection>
323     <refsection id="api_common_scilab_isVector">
324         <literallayout>
325             int <varname>scilab_isVector</varname>(
326             <link linkend="api_types_scilabEnv">
327                 <command>scilabEnv</command>
328             </link>
329             env,
330             <link linkend="api_types_scilabVar">
331                 <command>scilabVar</command>
332             </link>
333             var)
334             int <varname>scilab_isNVector</varname>(
335             <link linkend="api_types_scilabEnv">
336                 <command>scilabEnv</command>
337             </link>
338             env,
339             <link linkend="api_types_scilabVar">
340                 <command>scilabVar</command>
341             </link>
342             var, int n)
343             int <varname>scilab_isRowVector</varname>(
344             <link linkend="api_types_scilabEnv">
345                 <command>scilabEnv</command>
346             </link>
347             env,
348             <link linkend="api_types_scilabVar">
349                 <command>scilabVar</command>
350             </link>
351             var)
352             int <varname>scilab_isColVector</varname>(
353             <link linkend="api_types_scilabEnv">
354                 <command>scilabEnv</command>
355             </link>
356             env,
357             <link linkend="api_types_scilabVar">
358                 <command>scilabVar</command>
359             </link>
360             var)
361         </literallayout>
362         <para>
363             Use to check if variable <varname>var</varname> is a vector. <varname>n</varname> is the dimension to check, <code>scilab_isRowVector</code> is equivalente to <code>scilab_isNVector(env, var, 1)</code>
364         </para>
365     </refsection>
366     <refsection id="api_common_scilab_isHypermat">
367         <literal>
368             int <varname>scilab_isHypermat</varname>(
369             <link linkend="api_types_scilabEnv">
370                 <command>scilabEnv</command>
371             </link>
372             env,
373             <link linkend="api_types_scilabVar">
374                 <command>scilabVar</command>
375             </link>
376             var)
377         </literal>
378         <para>Return 1 for matrix with dimensions count is up to 2.</para>
379     </refsection>
380     <refsection id="api_common_scilab_overload">
381         <literal>
382             int <varname>scilab_overload</varname>(
383             <link linkend="api_types_scilabEnv">
384                 <command>scilabEnv</command>
385             </link>
386             env,
387             <link linkend="api_types_scilabVar">
388                 <command>scilabVar</command>
389             </link>
390             var, int nin,
391             <link linkend="api_types_scilabVar">
392                 <command>scilabVar</command>
393             </link>
394             *in, int nout,
395             <link linkend="api_types_scilabVar">
396                 <command>scilabVar</command>
397             </link>
398             *out)
399         </literal>
400         <para>
401             Call an overload function following type of <varname>var</varname>.
402         </para>
403         <para>
404             <varname>nin</varname>, <varname>in</varname>, <varname>nout</varname>, <varname>out</varname> must be used like in gateway prototype.
405         </para>
406     </refsection>
407     <refsection id="api_common_scilab_call">
408         <literal>
409             int <varname>scilab_call</varname>(
410             <link linkend="api_types_scilabEnv">
411                 <command>scilabEnv</command>
412             </link>
413             env, const wchar_t* name, int nin,
414             <link linkend="api_types_scilabVar">
415                 <command>scilabVar</command>
416             </link>
417             *in, int nout,
418             <link linkend="api_types_scilabVar">
419                 <command>scilabVar</command>
420             </link>
421             *out)
422         </literal>
423         <para>
424             Call function <varname>name</varname>.
425         </para>
426         <para>
427             <varname>nin</varname>, <varname>in</varname>, <varname>nout</varname>, <varname>out</varname> must be used like in gateway prototype.
428         </para>
429     </refsection>
430     <refsection>
431         <title>Examples</title>
432         <programlisting role="code_gateway">
433             <![CDATA[
434 #include "api_scilab.h"
435 #include "Scierror.h"
436 #include "localization.h"
437
438 const char fname[] = "overload_test";
439
440 int sci_overload_test(scilabEnv env, int nin, scilabVar* in, int nopt, scilabOpt opt, int nout, scilabVar* out)
441 {
442     if (nin < 1 || nin > 2)
443     {
444         Scierror(999, _("%s: Wrong number of input arguments: %d to %d expected.\n"), fname, 1, 2);
445         return STATUS_ERROR;
446     }
447
448     //call overload function
449     if (nin == 1)
450     {
451         return scilab_overload(env, in[0], nin, in, nout, out);
452     }
453     else // call function in[0] with in[1] as argument
454     {
455         wchar_t* name = NULL;
456         if (scilab_isString(env, in[0]) == 0 || scilab_isVector(env, in[0]) == 0)
457         {
458             Scierror(999, _("%s: Wrong type for input argument #%d: string expected.\n"), fname, 1);
459             return STATUS_ERROR;
460         }
461
462         scilab_getString(env, in[0], &name);
463
464         return scilab_call(env, name, nin - 1, in + 1, nout, out);
465     }
466     return STATUS_OK;
467 }
468             ]]>
469         </programlisting>
470     </refsection>
471     <refsection>
472         <title>Scilab test script</title>
473         <programlisting role="code_scilab">
474             <![CDATA[
475 mkdir(pathconvert(TMPDIR+"/api_c/"));
476 cd(pathconvert(TMPDIR+"/api_c/"));
477 copyfile(SCI+"/modules/api_scilab/tests/unit_tests/api_c/overload_test.c",pathconvert(TMPDIR+"/api_c/overload_test.c",%F));
478
479 ilib_build("liboverload",["overload_test","sci_overload_test", "csci6"],"overload_test.c",[],"","","");
480 exec("loader.sce");
481
482 a = rand(10, 10);
483 x = overload_test("cos", a);
484 assert_checkequal(x, cos(a));
485
486 function x = %s_overload_test(a)
487     x = cos(a);
488 endfunction
489
490 x = overload_test(a);
491 assert_checkequal(x, cos(a));
492             ]]>
493         </programlisting>
494     </refsection>
495     <refsection role="see also">
496         <title>See also</title>
497         <simplelist type="inline">
498             <member>
499                 <link linkend="api_double">API double</link>
500             </member>
501             <member>
502                 <link linkend="api_string">API string</link>
503             </member>
504             <member>
505                 <link linkend="api_string">API boolean</link>
506             </member>
507             <member>
508                 <link linkend="api_string">API int</link>
509             </member>
510             <member>
511                 <link linkend="api_string">API poly</link>
512             </member>
513             <member>
514                 <link linkend="api_string">API handle</link>
515             </member>
516             <member>
517                 <link linkend="api_string">API list</link>
518             </member>
519             <member>
520                 <link linkend="api_string">API struct</link>
521             </member>
522             <member>
523                 <link linkend="api_string">API cell</link>
524             </member>
525         </simplelist>
526     </refsection>
527 </refentry>