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