License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / api_scilab / help / en_US / E_boolean.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_boolean" xml:lang="en">
17     <refnamediv>
18         <refname>API boolean functions</refname>
19         <para>This page lists all the functions to manipulate Scilab native objects containing booleans</para>
20         <para></para>
21     </refnamediv>
22     <refsynopsisdiv>
23         <literal>
24             <link linkend="api_types_scilabVar">
25                 <command>scilabVar</command>
26             </link>
27             <varname>scilab_createBooleanMatrix</varname>(
28             <link linkend="api_types_scilabEnv">
29                 <command>scilabEnv</command>
30             </link>
31             env, int dim, const int* dims)
32         </literal>
33         <para>
34             Create a boolean matrix with <varname>dim</varname> dimensions (<varname>dims</varname>[0], <varname>dims</varname>[1], ..., <varname>dims</varname>[<varname>dim</varname>-1]).
35         </para>
36         <para></para>
37         <literal>
38             <link linkend="api_types_scilabVar">
39                 <command>scilabVar</command>
40             </link>
41             <varname>scilab_createBooleanMatrix2d</varname>(
42             <link linkend="api_types_scilabEnv">
43                 <command>scilabEnv</command>
44             </link>
45             env, int row, int col)
46         </literal>
47         <para>
48             Create an boolean matrix with 2 dimensions (<varname>row</varname>, <varname>col</varname>).
49         </para>
50         <para></para>
51         <literal>
52             <link linkend="api_types_scilabVar">
53                 <command>scilabVar</command>
54             </link>
55             <varname>scilab_createBoolean</varname>(
56             <link linkend="api_types_scilabEnv">
57                 <command>scilabEnv</command>
58             </link>
59             env, int val)
60         </literal>
61         <para>Create a scalar boolean.</para>
62         <para></para>
63         <literal>
64             <link linkend="api_types_scilabStatus">
65                 <command>scilabStatus</command>
66             </link>
67             <varname>scilab_getBooleanArray</varname>(
68             <link linkend="api_types_scilabEnv">
69                 <command>scilabEnv</command>
70             </link>
71             env, 
72             <link linkend="api_types_scilabVar">
73                 <command>scilabVar</command>
74             </link>
75             var, int** vals)
76         </literal>
77         <para>
78             Get pointer on internal array of boolean of <varname>var</varname>.
79         </para>
80         <para></para>
81         <literal>
82             <link linkend="api_types_scilabStatus">
83                 <command>scilabStatus</command>
84             </link>
85             <varname>scilab_getBoolean</varname>(
86             <link linkend="api_types_scilabEnv">
87                 <command>scilabEnv</command>
88             </link>
89             env, 
90             <link linkend="api_types_scilabVar">
91                 <command>scilabVar</command>
92             </link>
93             var, int* val)
94         </literal>
95         <para>Get boolean value from an scalar boolean variable.</para>
96         <para></para>
97         <literal>
98             <link linkend="api_types_scilabStatus">
99                 <command>scilabStatus</command>
100             </link>
101             <varname>scilab_setBooleanArray</varname>(
102             <link linkend="api_types_scilabEnv">
103                 <command>scilabEnv</command>
104             </link>
105             env, 
106             <link linkend="api_types_scilabVar">
107                 <command>scilabVar</command>
108             </link>
109             var, const int* vals)
110         </literal>
111         <para>
112             Set values of boolean variable <literal>var</literal>.
113         </para>
114         <para></para>
115         <literal>
116             <link linkend="api_types_scilabStatus">
117                 <command>scilabStatus</command>
118             </link>
119             <varname>scilab_setBoolean</varname>(
120             <link linkend="api_types_scilabEnv">
121                 <command>scilabEnv</command>
122             </link>
123             env, 
124             <link linkend="api_types_scilabVar">
125                 <command>scilabVar</command>
126             </link>
127             var, int val)
128         </literal>
129         <para>
130             Set value of a scalar boolean variable <literal>var</literal>.
131         </para>
132         <para></para>
133     </refsynopsisdiv>
134     <refsection>
135         <title>Examples</title>
136         <programlisting role="code_gateway">
137             <![CDATA[
138 #include "api_scilab.h"
139 #include "Scierror.h"
140 #include "localization.h"
141 #include "sciprint.h"
142 #include "sci_malloc.h"
143
144 const char fname[] = "boolean_test";
145
146 int sci_boolean_test(scilabEnv env, int nin, scilabVar* in, int nopt, scilabOpt opt, int nout, scilabVar* out)
147 {
148     int i = 0;
149     int inr1 = 0;
150     int inc1 = 0;
151     int size1 = 0;
152     int* in1 = NULL;
153
154     int in2 = 0;
155
156     int* out1 = NULL;
157
158     int* out2dims = NULL;
159     int* out2 = NULL;
160
161     int out3 = 0;
162
163     if (nin != 2)
164     {
165         Scierror(999, _("%s: Wrong number of input arguments: %d expected.\n"), fname, 2);
166         return API_ERROR;
167     }
168
169     if (nout != 3)
170     {
171         Scierror(999, _("%s: Wrong number of output arguments: %d expected.\n"), fname, 3);
172         return API_ERROR;
173     }
174
175     //in[0] : matrix 2d of boolean
176     if (scilab_isBoolean(env, in[0]) == 0 || scilab_isMatrix(env, in[0]) == 0)
177     {
178         Scierror(999, _("%s: Wrong type for input argument #%d: A boolean matrix expected.\n"), fname, 1);
179         return API_ERROR;
180     }
181
182     size1 = scilab_getDim2d(env, in[0], &inr1, &inc1);
183     scilab_getBooleanArray(env, in[0], &in1);
184
185     //in[1] : bool
186     if (scilab_isBoolean(env, in[1]) == 0 || scilab_isScalar(env, in[1]) == 0)
187     {
188         Scierror(999, _("%s: Wrong type for input argument #%d: A boolean expected.\n"), fname, 2);
189         return API_ERROR;
190     }
191
192     scilab_getBoolean(env, in[1], &in2);
193
194     //out1 : matrix 2d of boolean with same size of in[0]
195     out[0] = scilab_createBooleanMatrix2d(env, inr1, inc1);
196     if (scilab_getBooleanArray(env, out[0], &out1) != <link linkend="api_types_scilabStatus"><command>scilabStatus</command></link>::API_OK)
197     {
198         Scierror(999, "blabla\n");
199         return 1;
200     }
201
202     for (i = 0; i < size1; ++i)
203     {
204         out1[i] = in1[i] == 1 ? 0 : 1;
205     }
206
207     //out2 : 3d matrix of boolean
208     out2dims = (int*)MALLOC(3 * sizeof(int));
209     out2dims[0] = inr1;
210     out2dims[1] = inc1;
211     out2dims[2] = 2;
212
213     out[1] = scilab_createBooleanMatrix(env, 3, out2dims);
214     scilab_getBooleanArray(env, out[1], &out2);
215
216     for (i = 0; i < size1; ++i)
217     {
218         out2[i] = in1[i];
219         out2[i + size1] = in1[i] ? 0 : 1;
220     }
221
222     //out3 : bool
223     out[2] = scilab_createBoolean(env, in2 ? 0 : 1);
224     return API_OK;
225 }
226             ]]>
227         </programlisting>
228     </refsection>
229     <refsection>
230         <title>Scilab test script</title>
231         <programlisting role="code_scilab">
232             <![CDATA[
233 mkdir(pathconvert(TMPDIR+"/api_c/"));
234 cd(pathconvert(TMPDIR+"/api_c/"));
235 copyfile(SCI+"/modules/api_scilab/tests/unit_tests/api_c/boolean_test.c",pathconvert(TMPDIR+"/api_c/boolean_test.c",%F));
236
237 ilib_build("libboolean",["boolean_test","sci_boolean_test", "csci6"],"boolean_test.c",[],"","","");
238 exec("loader.sce");
239
240 in1 = rand(3,4) > 0.5;
241 in2 = rand() > 0.5;
242
243 [out1, out2, out3] = boolean_test(in1, in2);
244
245 assert_checkequal(out1, ~in1);
246 ref(:,:, 1) = in1;
247 ref(:,:, 2) = out1;
248 assert_checkequal(out2, ref);
249 assert_checkequal(out3, ~in2);
250             ]]>
251         </programlisting>
252     </refsection>
253 </refentry>