rewrite hypermat api for scilab 6
[scilab.git] / scilab / modules / api_scilab / help / en_US / hypermat / B_getHypermatOfDouble.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="getHypermatOfDouble" xml:lang="en">
14     <refnamediv>
15         <refname>getHypermatOfDouble</refname>
16         <refpurpose>
17             Get a hypermatrix of double variable.
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>SciErr getHypermatOfDouble(void* _pvCtx, int* _piAddress, int **_dims, int *_ndims, double* _pdblReal)</synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>Arguments</title>
26         <variablelist>
27             <varlistentry>
28                 <term>_pvCtx</term>
29                 <listitem>
30                     <para>
31                         Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
32                     </para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>_piAddress</term>
37                 <listitem>
38                     <para>
39                         Address of the Scilab variable.
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>_dims</term>
45                 <listitem>
46                     <para>
47                         the hypermatrix dimensions.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>_ndims</term>
53                 <listitem>
54                     <para>
55                         the number of dimensions.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>_pdblReal</term>
61                 <listitem>
62                     <para>
63                         Double values.
64                     </para>
65                 </listitem>
66             </varlistentry>
67         </variablelist>
68     </refsection>
69     <refsection>
70         <title>Return value</title>
71         <para>A SciErr struct, the field iErr would contain the error number (0 if no error).</para>
72     </refsection>
73     <refsection>
74         <title>Gateway Source</title>
75         <programlisting role="code_gateway">
76             <![CDATA[ 
77 #include "api_scilab.h"
78
79 int hypermatExample(char *fname,void* pvApiCtx)
80 {
81     SciErr sciErr;
82     int* piAddr = NULL;
83     int iType   = 0;
84     int iRet    = 0;
85
86     CheckInputArgument(pvApiCtx, 1, 1);
87     CheckOutputArgument(pvApiCtx, 0, 1);
88
89     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
90     if (sciErr.iErr)
91     {
92         printError(&sciErr, 0);
93         return 0;
94     }
95
96     if (isEmptyMatrix(pvApiCtx, piAddr))
97     {
98         iRet = createEmptyMatrix(pvApiCtx, nbInputArgument(pvApiCtx) + 1);
99         if (iRet)
100         {
101             return iRet;
102         }
103
104         AssignOutputVariable(pvApiCtx, 1) = 0;
105     }
106     else if (isHypermatType(pvApiCtx, piAddr))
107     {
108         int * dims = NULL;
109         int ndims;
110         double* pdblReal = NULL;
111         double* pdblImg = NULL;
112
113         if (isHypermatComplex(pvApiCtx, piAddr))
114         {
115             sciErr = getComplexHypermatOfDouble(pvApiCtx, piAddr, &dims, &ndims, &pdblReal, &pdblImg);
116             if (sciErr.iErr)
117             {
118                 printError(&sciErr, 0);
119                 return sciErr.iErr;
120             }
121
122             sciErr = createComplexHypermatOfDouble(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, pdblReal, pdblImg);
123             if (sciErr.iErr)
124             {
125                 printError(&sciErr, 0);
126                 return sciErr.iErr;
127             }
128         }
129         else
130         {
131             sciErr = getHypermatOfDouble(pvApiCtx, piAddr, &dims, &ndims, &pdblReal);
132             if (sciErr.iErr)
133             {
134                 printError(&sciErr, 0);
135                 return sciErr.iErr;
136             }
137
138             sciErr = createHypermatOfDouble(pvApiCtx, nbInputArgument(pvApiCtx) + 1, dims, ndims, pdblReal);
139             if (sciErr.iErr)
140             {
141                 printError(&sciErr, 0);
142                 return sciErr.iErr;
143             }
144         }
145
146         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
147     }
148
149     return 0;
150 }]]>
151         </programlisting>
152     </refsection>
153     <refsection>
154         <title>Scilab test script</title>
155         <programlisting role="code_scilab"><![CDATA[ 
156 a = hypermat([1 2 3], ones(1,6));
157 b = a + %i*hypermat([1 2 3], 1:6);
158
159 hypermatExample(a) == a
160 hypermatExample(b) == b
161  ]]></programlisting>
162     </refsection>
163 </refentry>