rewrite hypermat api for scilab 6
[scilab.git] / scilab / modules / api_scilab / help / en_US / hypermat / C_getHypermatOfInt.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) 2013  - Scilab Enterprises - Calixte DENIZET
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="getHypermatOfInt" xml:lang="en">
14     <refnamediv>
15         <refname>getHypermatOfInt</refname>
16         <refpurpose>
17             Get a hypermatrix of integer variable.
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>SciErr getHypermatOfInt8(void* _pvCtx, int* _piAddress, int **_dims, int *_ndims, char* _pcData)</synopsis>
23         <synopsis>SciErr getHypermatOfUnsignedInt8(void* _pvCtx, int* _piAddress, int **_dims, int *_ndims, unsigned char* _pucData)</synopsis>
24         <synopsis>SciErr getHypermatOfInt16(void* _pvCtx, int* _piAddress, int **_dims, int *_ndims, short* _psData)</synopsis>
25         <synopsis>SciErr getHypermatOfUnsignedInt16(void* _pvCtx, int* _piAddress, int **_dims, int *_ndims, unsigned short* _pusData)</synopsis>
26         <synopsis>SciErr getHypermatOfInt32(void* _pvCtx, int* _piAddress, int **_dims, int *_ndims, int* _piData)</synopsis>
27         <synopsis>SciErr getHypermatOfUnsignedInt32(void* _pvCtx, int* _piAddress, int **_dims, int *_ndims, unsigned int* _puiData)</synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>_pvCtx</term>
34                 <listitem>
35                     <para>
36                         Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>_piAddress</term>
42                 <listitem>
43                     <para>
44                         Address of the Scilab variable.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>_dims</term>
50                 <listitem>
51                     <para>
52                         the hypermatrix dimensions.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>_ndims</term>
58                 <listitem>
59                     <para>
60                         the number of dimensions.
61                     </para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>_p*Data</term>
66                 <listitem>
67                     <para>
68                         the data.
69                     </para>
70                 </listitem>
71             </varlistentry>
72         </variablelist>
73     </refsection>
74     <refsection>
75         <title>Return value</title>
76         <para>A SciErr struct, the field iErr would contain the error number (0 if no error).</para>
77     </refsection>
78     <refsection>
79         <title>Gateway Source</title>
80         <programlisting role="code_gateway">
81             <![CDATA[ 
82 #include "api_scilab.h"
83 #include "localization.h"
84
85 int hypermatIntExample(char *fname, void* pvApiCtx)
86 {
87     SciErr sciErr;
88     int* piAddr = NULL;
89     int iType   = 0;
90     int iRet    = 0;
91
92     CheckInputArgument(pvApiCtx, 1, 1);
93     CheckOutputArgument(pvApiCtx, 0, 1);
94
95     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
96     if (sciErr.iErr)
97     {
98         printError(&sciErr, 0);
99         return 0;
100     }
101
102     if (isEmptyMatrix(pvApiCtx, piAddr))
103     {
104         iRet = createEmptyMatrix(pvApiCtx, nbInputArgument(pvApiCtx) + 1);
105         if (iRet)
106         {
107             return iRet;
108         }
109
110         AssignOutputVariable(pvApiCtx, 1) = 0;
111     }
112     else if (isHypermatType(pvApiCtx, piAddr))
113     {
114         int * dims = NULL;
115         int ndims;
116         void * data = NULL;
117         int htype = 0;
118         int precision;
119
120         sciErr = getHypermatType(pvApiCtx, piAddr, &htype);
121         if (sciErr.iErr)
122         {
123             printError(&sciErr, 0);
124             return sciErr.iErr;
125         }
126
127         if (htype == sci_ints)
128         {
129             sciErr = getHypermatOfIntegerPrecision(pvApiCtx, piAddr, &precision);
130             if (sciErr.iErr)
131             {
132                 printError(&sciErr, 0);
133                 return sciErr.iErr;
134             }
135
136             switch (precision)
137             {
138             case SCI_INT8:
139                 sciErr = getHypermatOfInteger8(pvApiCtx, piAddr, &dims, &ndims, (char*)&data);
140                 if(sciErr.iErr)
141                 {
142                     printError(&sciErr, 0);
143                     return sciErr.iErr;
144                 }
145
146                 sciErr = createHypermatOfInteger8(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const char*)data);
147                 if (sciErr.iErr)
148                 {
149                     printError(&sciErr, 0);
150                     return sciErr.iErr;
151                 }
152                 break;
153             case SCI_UINT8:
154                 sciErr = getHypermatOfUnsignedInteger8(pvApiCtx, piAddr, &dims, &ndims, (unsigned char*)&data);
155                 if(sciErr.iErr)
156                 {
157                     printError(&sciErr, 0);
158                     return sciErr.iErr;
159                 }
160
161                 sciErr = createHypermatOfUnsignedInteger8(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const unsigned char*)data);
162                 if (sciErr.iErr)
163                 {
164                     printError(&sciErr, 0);
165                     return sciErr.iErr;
166                 }
167                 break;
168             case SCI_INT16:
169                 sciErr = getHypermatOfInteger16(pvApiCtx, piAddr, &dims, &ndims, (short*)&data);
170                 if(sciErr.iErr)
171                 {
172                     printError(&sciErr, 0);
173                     return sciErr.iErr;
174                 }
175
176                 sciErr = createHypermatOfInteger16(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const short*)data);
177                 if (sciErr.iErr)
178                 {
179                     printError(&sciErr, 0);
180                     return sciErr.iErr;
181                 }
182                 break;
183             case SCI_UINT16:
184                 sciErr = getHypermatOfUnsignedInteger16(pvApiCtx, piAddr, &dims, &ndims, (unsigned short*)&data);
185                 if(sciErr.iErr)
186                 {
187                     printError(&sciErr, 0);
188                     return sciErr.iErr;
189                 }
190
191                 sciErr = createHypermatOfUnsignedInteger16(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const unsigned short*)data);
192                 if (sciErr.iErr)
193                 {
194                     printError(&sciErr, 0);
195                     return sciErr.iErr;
196                 }
197                 break;
198             case SCI_INT32:
199                 sciErr = getHypermatOfInteger32(pvApiCtx, piAddr, &dims, &ndims, (int*)&data);
200                 if(sciErr.iErr)
201                 {
202                     printError(&sciErr, 0);
203                     return sciErr.iErr;
204                 }
205
206                 sciErr = createHypermatOfInteger32(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const int*)data);
207                 if (sciErr.iErr)
208                 {
209                     printError(&sciErr, 0);
210                     return sciErr.iErr;
211                 }
212                 break;
213             case SCI_UINT32:
214                 sciErr = getHypermatOfUnsignedInteger32(pvApiCtx, piAddr, &dims, &ndims, (unsigned int*)&data);
215                 if(sciErr.iErr)
216                 {
217                     printError(&sciErr, 0);
218                     return sciErr.iErr;
219                 }
220
221                 sciErr = createHypermatOfUnsignedInteger32(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const unsigned int*)data);
222                 if (sciErr.iErr)
223                 {
224                     printError(&sciErr, 0);
225                     return sciErr.iErr;
226                 }
227                 break;
228             }
229             case SCI_INT64:
230                 sciErr = getHypermatOfInteger64(pvApiCtx, piAddr, &dims, &ndims, (long long*)&data);
231                 if (sciErr.iErr)
232                 {
233                     printError(&sciErr, 0);
234                     return sciErr.iErr;
235                 }
236
237                 sciErr = createHypermatOfInteger64(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const long long*)data);
238                 if (sciErr.iErr)
239                 {
240                     printError(&sciErr, 0);
241                     return sciErr.iErr;
242                 }
243                 break;
244             case SCI_UINT64:
245                 sciErr = getHypermatOfUnsignedInteger64(pvApiCtx, piAddr, &dims, &ndims, (unsigned long long*)&data);
246                 if (sciErr.iErr)
247                 {
248                     printError(&sciErr, 0);
249                     return sciErr.iErr;
250                 }
251
252                 sciErr = createHypermatOfUnsignedInteger64(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, (const unsigned long long*)data);
253                 if (sciErr.iErr)
254                 {
255                     printError(&sciErr, 0);
256                     return sciErr.iErr;
257                 }
258                 break;
259             }
260         }
261         else
262         {
263             Scierror(999, _("%s: Wrong type for input argument #%d: An integer expected.\n"), fname, 1);
264             return 1;
265         }
266
267         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
268     }
269
270     return 0;
271 }]]>
272         </programlisting>
273     </refsection>
274     <refsection>
275         <title>Scilab test script</title>
276         <programlisting role="code_scilab"><![CDATA[ 
277 a = hypermat([1 2 3], int8(1:6));
278 b = hypermat([1 2 3], uint8(1:6));
279 c = hypermat([1 2 3], int16(1:6));
280 d = hypermat([1 2 3], uint16(1:6));
281 e = hypermat([1 2 3], int32(1:6));
282 f = hypermat([1 2 3], uint32(1:6));
283
284 hypermatExampleInt(a) == a
285 hypermatExampleInt(b) == b
286 hypermatExampleInt(c) == c
287 hypermatExampleInt(d) == d
288 hypermatExampleInt(e) == e
289 hypermatExampleInt(f) == f
290  ]]></programlisting>
291     </refsection>
292 </refentry>