bug 7040 : Modification of the example and the description for getMatrixOfIntegerPrec...
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / int_getmatrixofintegerprecision_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.1-en.txt
11  *
12  -->
13 <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="int_getmatrixofintegerprecision_API" xml:lang="en">
14     <refnamediv>
15         <refname>Integer Precision (Scilab gateway)</refname>
16         <refpurpose>
17             How to get precision of an integer matrix.
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>SciErr getMatrixOfIntegerPrecision(void* _pvCtx, int* _piAddress, int* _piPrecision)</synopsis>
23         <synopsis>SciErr getNamedMatrixOfIntegerPrecision(void* _pvCtx, const char* _pstName, int* _piPrecision)</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>_pvCtx</term>
30                 <listitem>
31                     <para>
32                         Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>_piAddress</term>
38                 <listitem>
39                     <para>
40                         Address of the variable.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>_pstName</term>
46                 <listitem>
47                     <para>
48                         Name of the variable for "named" functions.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>_piPrecision</term>
54                 <listitem>
55                     <para>
56                         Return precision of an integer variable. If value is greater then 10 then the variable is unsigned.
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>SciErr</term>
62                 <listitem>
63                     <para>
64                         Error structure where is stored errors messages history and first error number.
65                     </para>
66                 </listitem>
67             </varlistentry>
68         </variablelist>
69     </refsection>
70     <refsection>
71         <title>Description</title>
72         <para>This help describes how to get precision of an integer matrix.</para>
73     </refsection>
74     <refsection>
75         <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/common_function_api.c-->
76         <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/common_function.tst-->
77         <!--Lib_name: common_function-->
78         <!--Func_list: common_function-->
79         <title>Gateway Source</title>
80         <programlisting role="code_gateway">
81             <![CDATA[ 
82 #include "api_scilab.h"
83 SciErr printf_info(int _iVar);
84
85 int common_function(char *fname,unsigned long fname_len)
86 {
87         SciErr sciErr;
88         int i;
89         int *piAddr1    = NULL;
90         int iBool       = 0;
91
92         for(i = 0 ; i < nbInputArgument(pvApiCtx) ; i++)
93         {
94                 sciErr = printf_info(i + 1);
95                 if(sciErr.iErr)
96                 {
97                         printError(&sciErr, 0);
98                         break;
99                 }
100                 sciprint("\n\n");
101         }
102
103         //1 for true, 0 for false
104         iBool = sciErr.iErr == 0 ? 1 : 0;
105
106         sciErr = createMatrixOfBoolean(pvApiCtx, nbInputArgument(pvApiCtx) + 1, 1, 1, &iBool);
107         if(sciErr.iErr)
108         {
109                 printError(&sciErr, 0);
110                 return 0;
111         }
112
113         //assign allocated variables to Lhs position
114         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
115         return 0;
116 }
117
118 SciErr printf_info(int _iVar)
119 {
120         SciErr sciErr;
121         int* piAddr     = NULL;
122         int iType       = 0;
123
124         sciErr = getVarAddressFromPosition(pvApiCtx, _iVar, &piAddr);
125         if(sciErr.iErr)
126         {
127                 return sciErr;
128         }
129
130         sciprint("Variable %d information:\n", _iVar);
131
132         sciErr = getVarType(pvApiCtx, piAddr, &iType);
133         if(sciErr.iErr)
134         {
135                 return sciErr;
136         }
137
138         sciprint("\tType: ");
139         if(iType == sci_ints)
140         {
141                 char pstSigned[]    = "signed";
142                 char pstUnsigned[]  = "unsigned";
143                 char* pstSign       = pstSigned;
144                 int iPrec           = 0;
145
146                 sciErr = getMatrixOfIntegerPrecision(pvApiCtx, piAddr, &iPrec);
147                 if(sciErr.iErr)
148                 {
149                         return sciErr;
150                 }
151
152                 if(iPrec > 10)
153                 {
154                         pstSign = pstUnsigned;
155                 }
156
157                 sciprint("%s integer %d bits\n", pstSign, (iPrec % 10) * 8);
158     }
159         else
160         {
161                 sciprint("Not manage by this function\n");
162                 return sciErr;
163     }
164         
165         return sciErr;
166 }
167  ]]>
168         </programlisting>
169     </refsection>
170     <refsection>
171         <title>Scilab test script</title>
172         <programlisting role="code_scilab"><![CDATA[ 
173 l1 = [1,2*%i,3;%i,2,3*%i];
174 l2 = ["may","the";"puffin","be";"with","you"];
175 l3 = int8([1,2,3]);
176 l4 = uint16([1000,2000,3000]);
177 l5 = list(l1,l2,l3);
178 l = list(l1,l2,l3,l4,l5);
179 common_function(l(1:$))
180  ]]></programlisting>
181     </refsection>
182 </refentry>