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