License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / api_scilab / help / en_US / C_double.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) 2015  - Scilab Enterprises - Antoine ELIAS
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="api_double" xml:lang="en">
17     <refnamediv>
18         <refname>API double functions</refname>
19         <para>This page lists all the functions to manipulate Scilab native objects containing doubles.</para>
20         <para></para>
21     </refnamediv>
22     <refsynopsisdiv>
23         <refsection id="api_double_scilab_createEmptyMatrix">
24             <literal>
25                 <link linkend="api_types_scilabVar">
26                     <command>scilabVar</command>
27                 </link>
28                 <varname>scilab_createEmptyMatrix</varname>(
29                 <link linkend="api_types_scilabEnv">
30                     <command>scilabEnv</command>
31                 </link>
32                 env)
33             </literal>
34             <para>Create an empty matrix.</para>
35         </refsection>
36         <refsection id="api_double_scilab_createDoubleMatrix">
37             <literal>
38                 <link linkend="api_types_scilabVar">
39                     <command>scilabVar</command>
40                 </link>
41                 <varname>scilab_createDoubleMatrix</varname>(
42                 <link linkend="api_types_scilabEnv">
43                     <command>scilabEnv</command>
44                 </link>
45                 env, int dim, const int* dims, int complex)
46             </literal>
47             <para>
48                 Create a double matrix with <varname>dim</varname> dimensions (<varname>dims</varname>[0], <varname>dims</varname>[1], ..., <varname>dims</varname>[<varname>dim</varname>-1]).
49             </para>
50             <para>
51                 <varname>complex</varname>: 0 to real matrix or 1 to complex matrix
52             </para>
53         </refsection>
54         <refsection id="api_double_scilab_createDoubleMatrix2d">
55             <literal>
56                 <link linkend="api_types_scilabVar">
57                     <command>scilabVar</command>
58                 </link>
59                 <varname>scilab_createDoubleMatrix2d</varname>(
60                 <link linkend="api_types_scilabEnv">
61                     <command>scilabEnv</command>
62                 </link>
63                 env, int row, int col, int complex)
64             </literal>
65             <para>
66                 Create a double matrix with 2 dimensions (<varname>row</varname>, <varname>col</varname>).
67             </para>
68             <para>
69                 <varname>complex</varname>: 0 to real matrix or 1 to complex matrix
70             </para>
71         </refsection>
72         <refsection id="api_double_scilab_createDouble">
73             <literal>
74                 <link linkend="api_types_scilabVar">
75                     <command>scilabVar</command>
76                 </link>
77                 <varname>scilab_createDouble</varname>(
78                 <link linkend="api_types_scilabEnv">
79                     <command>scilabEnv</command>
80                 </link>
81                 env, double real)
82             </literal>
83             <para>Create a scalar double.</para>
84         </refsection>
85         <refsection id="api_double_scilab_createDoubleComplex">
86             <literal>
87                 <link linkend="api_types_scilabVar">
88                     <command>scilabVar</command>
89                 </link>
90                 <varname>scilab_createDoubleComplex</varname>(
91                 <link linkend="api_types_scilabEnv">
92                     <command>scilabEnv</command>
93                 </link>
94                 env, double real, double img)
95             </literal>
96             <para>Create a scalar complex double.</para>
97         </refsection>
98         <refsection id="api_double_scilab_getDoubleArray">
99             <literal>
100                 <link linkend="api_types_scilabStatus">
101                     <command>scilabStatus</command>
102                 </link>
103                 <varname>scilab_getDoubleArray</varname>(
104                 <link linkend="api_types_scilabEnv">
105                     <command>scilabEnv</command>
106                 </link>
107                 env, 
108                 <link linkend="api_types_scilabVar">
109                     <command>scilabVar</command>
110                 </link>
111                 var, double** real)
112             </literal>
113             <para>
114                 Get pointer on internal array of double of <literal>var</literal>.
115             </para>
116         </refsection>
117         <refsection id="api_double_scilab_getDoubleComplexArray">
118             <literal>
119                 <link linkend="api_types_scilabStatus">
120                     <command>scilabStatus</command>
121                 </link>
122                 <varname>scilab_getDoubleComplexArray</varname>(
123                 <link linkend="api_types_scilabEnv">
124                     <command>scilabEnv</command>
125                 </link>
126                 env, 
127                 <link linkend="api_types_scilabVar">
128                     <command>scilabVar</command>
129                 </link>
130                 var, double** real, double** img)
131             </literal>
132             <para>
133                 Get pointers on internal arrays of double of <literal>var</literal>.
134             </para>
135         </refsection>
136         <refsection id="api_double_scilab_getDouble">
137             <literal>
138                 <link linkend="api_types_scilabStatus">
139                     <command>scilabStatus</command>
140                 </link>
141                 <varname>scilab_getDouble</varname>(
142                 <link linkend="api_types_scilabEnv">
143                     <command>scilabEnv</command>
144                 </link>
145                 env, 
146                 <link linkend="api_types_scilabVar">
147                     <command>scilabVar</command>
148                 </link>
149                 var, double* real)
150             </literal>
151             <para>Get double value from an scalar double variable.</para>
152         </refsection>
153         <refsection id="api_double_scilab_getDoubleComplex">
154             <literal>
155                 <link linkend="api_types_scilabStatus">
156                     <command>scilabStatus</command>
157                 </link>
158                 <varname>scilab_getDoubleComplex</varname>(
159                 <link linkend="api_types_scilabEnv">
160                     <command>scilabEnv</command>
161                 </link>
162                 env, 
163                 <link linkend="api_types_scilabVar">
164                     <command>scilabVar</command>
165                 </link>
166                 var, double* real, double* img)
167             </literal>
168             <para>Get double values from an scalar double variable.</para>
169         </refsection>
170         <refsection id="api_double_scilab_setDoubleArray">
171             <literal>
172                 <link linkend="api_types_scilabStatus">
173                     <command>scilabStatus</command>
174                 </link>
175                 <varname>scilab_setDoubleArray</varname>(
176                 <link linkend="api_types_scilabEnv">
177                     <command>scilabEnv</command>
178                 </link>
179                 env, 
180                 <link linkend="api_types_scilabVar">
181                     <command>scilabVar</command>
182                 </link>
183                 var, const double* real)
184             </literal>
185             <para>
186                 Set values of double variable <literal>var</literal>.
187             </para>
188         </refsection>
189         <refsection id="api_double_scilab_setDoubleComplexArray">
190             <literal>
191                 <link linkend="api_types_scilabStatus">
192                     <command>scilabStatus</command>
193                 </link>
194                 <varname>scilab_setDoubleComplexArray</varname>(
195                 <link linkend="api_types_scilabEnv">
196                     <command>scilabEnv</command>
197                 </link>
198                 env, 
199                 <link linkend="api_types_scilabVar">
200                     <command>scilabVar</command>
201                 </link>
202                 var, const double* real, const double* img)
203             </literal>
204             <para>
205                 Set values of complex double variable <literal>var</literal>.
206             </para>
207         </refsection>
208         <refsection id="api_double_scilab_setDouble">
209             <literal>
210                 <link linkend="api_types_scilabStatus">
211                     <command>scilabStatus</command>
212                 </link>
213                 <varname>scilab_setDouble</varname>(
214                 <link linkend="api_types_scilabEnv">
215                     <command>scilabEnv</command>
216                 </link>
217                 env, 
218                 <link linkend="api_types_scilabVar">
219                     <command>scilabVar</command>
220                 </link>
221                 var, double real)
222             </literal>
223             <para>
224                 Set value of a scalar double variable <literal>var</literal>.
225             </para>
226         </refsection>
227         <refsection id="api_double_scilab_setDoubleComplex">
228             <literal>
229                 <link linkend="api_types_scilabStatus">
230                     <command>scilabStatus</command>
231                 </link>
232                 <varname>scilab_setDoubleComplex</varname>(
233                 <link linkend="api_types_scilabEnv">
234                     <command>scilabEnv</command>
235                 </link>
236                 env, 
237                 <link linkend="api_types_scilabVar">
238                     <command>scilabVar</command>
239                 </link>
240                 var, double real, double img)
241             </literal>
242             <para>
243                 Set values of a scalar complex double variable <literal>var</literal>.
244             </para>
245         </refsection>
246     </refsynopsisdiv>
247     <refsection>
248         <title>Examples</title>
249         <programlisting role="code_gateway">
250             <![CDATA[
251 #include "api_scilab.h"
252 #include "Scierror.h"
253 #include "localization.h"
254 #include "sciprint.h"
255 #include "sci_malloc.h"
256
257 const char fname[] = "double_test";
258
259 int sci_double_test(scilabEnv env, int nin, scilabVar* in, int nopt, scilabOpt opt, int nout, scilabVar* out)
260 {
261     int i = 0;
262     int inr1 = 0;
263     int inc1 = 0;
264     int size1 = 0;
265     double* in1 = NULL;
266
267     double in2 = 0;
268
269     double* out1 = NULL;
270
271     int* out2dims = NULL;
272     double* out2 = NULL;
273
274     double out3 = 0;
275
276     if (nin != 2)
277     {
278         Scierror(999, _("%s: Wrong number of input arguments: %d expected.\n"), fname, 2);
279         return SCILAB_ERROR;
280     }
281
282     if (nout != 3)
283     {
284         Scierror(999, _("%s: Wrong number of output arguments: %d expected.\n"), fname, 3);
285         return SCILAB_ERROR;
286     }
287
288     //in[0] : matrix 2d of double
289     if (scilab_isDouble(env, in[0]) == 0 || scilab_isMatrix(env, in[0]) == 0)
290     {
291         Scierror(999, _("%s: Wrong type for input argument #%d: A double matrix expected.\n"), fname, 1);
292         return SCILAB_ERROR;
293     }
294
295     size1 = scilab_getDim2d(env, in[0], &inr1, &inc1);
296     scilab_getDoubleArray(env, in[0], &in1);
297
298     //in[1] : double
299     if (scilab_isDouble(env, in[1]) == 0 || scilab_isScalar(env, in[1]) == 0)
300     {
301         Scierror(999, _("%s: Wrong type for input argument #%d: A double expected.\n"), fname, 2);
302         return SCILAB_ERROR;
303     }
304
305     scilab_getDouble(env, in[1], &in2);
306
307     //out1 : matrix 2d of double with same size of in[0]
308     out[0] = scilab_createDoubleMatrix2d(env, inr1, inc1, 0);
309     scilab_getDoubleArray(env, out[0], &out1);
310
311     for (i = 0; i < size1; ++i)
312     {
313         out1[i] = in1[i] * 10;
314     }
315
316     //out2 : 3d matrix of double
317     out2dims = (int*)MALLOC(3 * sizeof(int));
318     out2dims[0] = inr1;
319     out2dims[1] = inc1;
320     out2dims[2] = 2;
321
322     out[1] = scilab_createDoubleMatrix(env, 3, out2dims, 0);
323     scilab_getDoubleArray(env, out[1], &out2);
324
325     for (i = 0; i < size1; ++i)
326     {
327         out2[i] = in1[i] * 10;
328         out2[i + size1] = in1[i] * 100;
329     }
330
331     //out3 : double
332     out[2] = scilab_createDouble(env, in2 * 1000);
333     return SCILAB_OK;
334 }
335             ]]>
336         </programlisting>
337     </refsection>
338     <refsection>
339         <title>Scilab test script</title>
340         <programlisting role="code_scilab">
341             <![CDATA[
342 mkdir(pathconvert(TMPDIR+"/api_c/"));
343 cd(pathconvert(TMPDIR+"/api_c/"));
344 copyfile(SCI+"/modules/api_scilab/tests/unit_tests/api_c/double_test.c",pathconvert(TMPDIR+"/api_c/double_test.c",%F));
345
346 ilib_build("libdouble", ["double_test","sci_double_test", "csci6"],"double_test.c",[],"","","");
347 exec("loader.sce");
348
349 in1 = rand(3,4);
350 in2 = rand();
351
352 [out1, out2, out3] = double_test(in1, in2);
353
354 assert_checkequal(out1, in1 * 10);
355 ref(:,:, 1) = in1 * 10;
356 ref(:,:, 2) = in1 * 100;
357 assert_checkequal(out2, ref);
358 assert_checkequal(out3, in2 * 1000);
359 disp("OK");
360             ]]>
361         </programlisting>
362     </refsection>
363 </refentry>