20d63a1d1ad45d35dac9f958f3b146cd4aee0484
[scilab.git] / scilab / modules / api_scilab / help / en_US / common_getvardimension_api.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) 2009  - DIGITEO - Antoine ELIAS
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry version="5.0-subset Scilab" xml:id="Common_getvardimension_API"
14           xml:lang="en" xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20
21     <refnamediv>
22         <refname>Variable Dimension (Scilab gateway)</refname>
23
24         <refpurpose>
25             How to get dimension of a variable stored as matrix.
26         </refpurpose>
27     </refnamediv>
28     <refsynopsisdiv>
29       <title>Calling Sequence</title>
30       <synopsis>int getVarDimension(int* _piAddress, int* _piRows, int* _piCols)</synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Parameters</title>
34         <variablelist>
35             <varlistentry>
36                 <term>_piAddress</term>
37                 <listitem>
38                     <para>
39                         Address of the variable.
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>_piRows</term>
45                 <listitem>
46                     <para>
47                         Return number of rows.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>_piCols</term>
53                 <listitem>
54                     <para>
55                         Return number of columns.
56                     </para>
57                 </listitem>
58             </varlistentry>
59         </variablelist>
60     </refsection>
61     <refsection>
62       <title>Description</title>
63       <para>This help describes how to get dimension of a variable in a gateway.</para>
64     </refsection>
65     <refsection>
66         <!--File_gateway: SCI/modules/core/tests/unit_tests/commom_function_api.c-->
67         <!--File_scilab: SCI/modules/core/tests/unit_tests/commom_function.tst-->
68         <!--Lib_name: commom_function-->
69         <!--Func_list: commom_function-->
70         <title>Gateway Source</title>
71         <programlisting role="code_gateway">
72             <![CDATA[
73 int printf_info(int _iVar);
74
75 int commom_function(char *fname,unsigned long fname_len)
76 {
77     int i;
78     int iRet        = 0;
79     int *piAddr1    = NULL;
80
81     for(i = 0 ; i < Rhs ; i++)
82     {
83         iRet = printf_info(i + 1);
84         if(iRet)
85         {
86             break;
87         }
88         sciprint("\n\n");
89     }
90
91     if(iRet)
92     {
93         //1 for true, 0 for false
94         iRet = !iRet;
95         createMatrixOfBoolean(1, 1, 1, &iRet);
96         //assign allocated variables to Lhs position
97         LhsVar(1) = 1;
98     }
99     else
100     {
101         //assign allocated variables to Lhs position
102         LhsVar(1) = 0;
103     }
104
105     return 0;
106 }
107
108 int printf_info(int _iVar)
109 {
110     int* piAddr     = NULL;
111     int iRet        = 0;
112     int iType       = 0;
113     int iRows       = 0;
114     int iCols       = 0;
115     int iItem       = 0;
116     int iComplex    = 0;
117
118     iRet = getVarAddressFromPosition(_iVar, &piAddr);
119     if(iRet)
120     {
121         return 1;
122     }
123
124     sciprint("Variable %d information:\n", _iVar);
125     iType = getVarType(piAddr);
126     sciprint("\tType: ");
127     switch(iType)
128     {
129         case sci_matrix : 
130             sciprint("double\n");
131             break;
132         case sci_poly : 
133             sciprint("polynomial\n");
134             break;
135         case sci_boolean : 
136            sciprint("boolean\n");
137            break;
138         case sci_sparse : 
139             sciprint("sparse\n");
140             break;
141         case sci_boolean_sparse : 
142             sciprint("boolean_sparse\n");
143             break;
144         case sci_ints : 
145         {
146             char pstSigned[]    = "signed";
147             char pstUnsigned[]  = "unsigned";
148             char* pstSign       = pstSigned;
149
150             int iPrec           = 0;
151             iRet = getMatrixOfIntegerPrecision(piAddr, &iPrec);
152
153             if(iPrec > 10)
154             {
155                 pstSign = pstUnsigned;
156             }
157
158             sciprint("%s integer %d bits\n", pstSign, (iPrec % 10) * 8);
159         }
160         break;
161         case sci_strings : 
162             sciprint("strings\n");
163             break;
164         case sci_list : 
165             sciprint("list\n");
166             break;
167         case sci_tlist : 
168             sciprint("tlist\n");
169             break;
170         case sci_mlist : 
171             sciprint("mlist\n");
172             break;
173         default :
174             sciprint("Not managed by this function\n");
175             return 0;
176     }
177
178     if(isVarComplex(piAddr))
179     {
180         sciprint("\tComplex: Yes\n");
181     }
182
183     sciprint("\tDimensions: ");
184     if(isVarMatrixType(piAddr))
185     {
186         getVarDimension(piAddr, &iRows, &iCols);
187         sciprint("%d x %d", iRows, iCols);
188     }
189     else
190     {
191         getListItemNumber(piAddr, &iItem);
192         sciprint("%d", iItem);
193     }
194     return 0;
195 }
196         ]]>
197         </programlisting>
198     </refsection>
199
200     <refsection>
201         <title>Scilab test script</title>
202         <programlisting role="code_scilab">
203             <![CDATA[
204 l1 = [1,2*%i,3;%i,2,3*%i];
205 l2 = ["may","the";"puffin","be";"with","you"];
206 l3 = int8([1,2,3]);
207 l4 = uint16([1000,2000,3000]);
208 l5 = list(l1,l2,l3);
209 l = list(l1,l2,l3,l4,l5);
210 commom_function(l(1:$))
211             ]]>
212         </programlisting>
213     </refsection>
214 </refentry>