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>