* Bug 16609 fixed: bitcmp() upgraded for Scilab 6
[scilab.git] / scilab / modules / elementary_functions / help / en_US / bitwise / bitcmp.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) 2020 - Samuel GOUGEON
5  *
6  * This file is hereby licensed under the terms of the GNU GPL v2.0,
7  * pursuant to article 5.3.4 of the CeCILL v.2.1.
8  * This file was originally licensed under the terms of the CeCILL v2.1,
9  * and continues to be available under such terms.
10  * For more information, see the COPYING file which you should have received
11  * along with this program.
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
15       xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
16       xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
17       xmlns:scilab="http://www.scilab.org" xml:id="bitcmp" xml:lang="en">
18     <refnamediv>
19         <refname>bitcmp</refname>
20         <refpurpose>bitwise complement of integers</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>
25             y = bitcmp(x)
26             y = bitcmp(x, bitnum)
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>x, y</term>
34                 <listitem>
35                     arrays of signed or unsigned integers (int8, .., uint64), or of positive decimal
36                     integers. Hypermatrix supported. <varname>x</varname> and <varname>y</varname>
37                     have the same integer type and the same size.
38                     <para/>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>bitnum</term>
43                 <listitem>
44                     positive encoded or decimal integer, or array of positive encoded or decimal
45                     integers of size equal to size(x): bits #1 to #bitnum of <varname>x</varname>
46                     are considered and inversed. According to the integer type of
47                     <varname>x</varname>, <varname>bitnum</varname> must be in the interval
48                     <literal>[1, bitmax]</literal> with bitmax as follows:
49                     <table>
50                         <tr><th>inttype :</th>
51                             <td>int8</td>
52                             <td>uint8</td>
53                             <td>int16</td>
54                             <td>uint16</td>
55                             <td>int32</td>
56                             <td>uint32</td>
57                             <td>int64</td>
58                             <td>uint64</td>
59                             <td>decimal</td>
60                         </tr>
61                         <tr><th>bitmax :</th>
62                             <td>8</td>
63                             <td>8</td>
64                             <td>16</td>
65                             <td>16</td>
66                             <td>32</td>
67                             <td>32</td>
68                             <td>64</td>
69                             <td>64</td>
70                             <td>1024</td>
71                         </tr>
72                     </table>
73                     <para/>
74                     The default <varname>bitnum</varname> value depends on the input integer
75                     type:
76                     <itemizedlist>
77                         <listitem>
78                             <literal>bitnum = bitmax</literal> for encoded integers
79                         </listitem>
80                         <listitem>
81                             <literal>bitnum = 53</literal> for decimal integers
82                             <literal>x ≤ 1/%eps</literal>
83                         </listitem>
84                         <listitem>
85                             <literal>bitnum = int(log2(x))+1</literal> for decimal integers
86                             <literal>x > 1/%eps</literal>.
87                         </listitem>
88                     </itemizedlist>
89                     <para/>
90                 </listitem>
91             </varlistentry>
92         </variablelist>
93     </refsection>
94     <refsection>
95         <title>Description</title>
96         <para>
97             <literal>bitcmp(x)</literal> computes the binary complement of each element of
98             <varname>x</varname>, and provides it in the corresponding element of <varname>y</varname>.
99         </para>
100         <para>
101             In the following description, 2^0 corresponds to the bit #1. An integer whose highest
102             bit on is #n, is in <literal>[2^(n-1), 2^n-1]</literal>.
103         </para>
104         <para>
105             For <varname>x</varname> such that <literal>abs(x) ≥ 2^bitnum</literal>,
106             its bits <literal>#(bitnum+1)</literal> to <literal>#(int(log2(x))+1)</literal>
107             are ignored. Only its bits <literal>#1</literal> to <literal>#bitnum</literal>
108             are considered and inversed.
109         </para>
110         <para>
111             Example:
112             <screen>
113 --> bitget(180, 1:8)
114  ans  =
115    0.   0.   1.   0.   1.   1.   0.   1.
116 --> bitcmp(180, 4)
117  ans  =
118    11.
119 --> bitget(11, 1:8)
120  ans  =
121    1.   1.   0.   1.   0.   0.   0.   0.
122 </screen>
123         </para>
124         <para>
125             For <varname>x</varname> such that <literal>abs(x) &lt; 2^bitnum</literal>,
126             bits <literal>#(int(log2(x))+2)</literal> to <literal>#bitnum</literal> are padded
127             with 0. Then all bits <literal>#1</literal> to <literal>#bitnum</literal> are considered
128             and inversed.
129         </para>
130         <para>
131             Example:
132             <screen>
133 --> x = 30; int(log2(30))+2
134  ans  =
135    6.
136 --> bitget(30, 1:10)
137  ans  =
138    0.   1.   1.   1.   1.   0.   0.   0.   0.   0.
139 --> bitcmp(30, 7)
140  ans  =
141    97.
142 --> bitget(97, 1:10)
143  ans  =
144    1.   0.   0.   0.   0.   1.   1.   0.   0.   0.
145 </screen>
146         </para>
147     </refsection>
148     <refsection>
149         <title>Examples</title>
150         <programlisting role="example"><![CDATA[
151 x = uint8(13);
152 b = bitget(x, 1:8)
153 c = bitcmp(x, 8)
154 bitget(c, 1:8)
155 1 - b
156    ]]></programlisting>
157         <screen><![CDATA[
158 --> b = bitget(x, 1:8)
159  b  =
160   1  0  1  1  0  0  0  0
161
162 --> c = bitcmp(x, 8)
163  c  =
164   242
165
166 --> bitget(c, 1:8)
167  ans  =
168   0  1  0  0  1  1  1  1
169
170 --> 1 - b
171  ans  =
172   0  1  0  0  1  1  1  1
173 ]]></screen>
174         <para/>
175         <para>
176         Negative encoded integers are accepted:
177         </para>
178         <programlisting role="example"><![CDATA[
179 bitcmp(int8([-71 -34 -1 0 33 70]))
180 bitcmp(int8([-71 -34 -1 0 33 70]), 8)
181 bitcmp(int8([-71 -34 -1 0 33 70]), 7)
182 bitcmp(int8([-71 -34 -1 0 33 70]), 6)
183 bitcmp(int8([-71 -34 -1 0 33 70]), 5)
184 bitcmp(int8([-71 -34 -1 0 33 70]), 4)
185      ]]></programlisting>
186         <screen><![CDATA[
187 --> bitcmp(int8([-71 -34 -1 0 33 70]))
188  ans  =
189   70  33  0 -1 -34 -71
190
191 --> bitcmp(int8([-71 -34 -1 0 33 70]), 8)
192  ans  =
193   70  33  0 -1 -34 -71
194
195 --> bitcmp(int8([-71 -34 -1 0 33 70]), 7)
196  ans  =
197   70  33  0  127  94  57
198
199 --> bitcmp(int8([-71 -34 -1 0 33 70]), 6)
200  ans  =
201   6  33  0  63  30  57
202
203 --> bitcmp(int8([-71 -34 -1 0 33 70]), 5)
204  ans  =
205   6  1  0  31  30  25
206
207 --> bitcmp(int8([-71 -34 -1 0 33 70]), 4)
208  ans  =
209   6  1  0  15  14  9
210 ]]></screen>
211         <para/>
212         <para>
213             We can work with 64-bit big integers:
214         </para>
215         <programlisting role="example"><![CDATA[
216 b = (rand(1,62)<0.5)*1;
217 x = sum(b .* (uint64(2).^(0:61)))
218 r = bitcmp(x)
219 bg = bitget(r, 1:62);
220 [msprintf("%d ",b(:)) ; msprintf("%d ",bg(:))]
221      ]]></programlisting>
222         <screen><![CDATA[
223 --> x = sum(b .* (uint64(2).^(0:61)))
224  x  =
225   4154509482123930814
226
227 --> r = bitcmp(x)
228  r  =
229   14292234591585620801
230
231 --> bg = bitget(r, 1:62);
232 --> [msprintf("%d ",b(:)) ; msprintf("%d ",bg(:))]
233  ans  =
234   "0 1 1 1 1 1 0 1 0 0 1 1 0 1 0 0 ... 1 0 0 0 0 1 0 0 1 1 1 1 1 0 0 1 0 1 1 0 0 1 1 1 "
235   "1 0 0 0 0 0 1 0 1 1 0 0 1 0 1 1 ... 0 1 1 1 1 0 1 1 0 0 0 0 0 1 1 0 1 0 0 1 1 0 0 0 "
236 ]]></screen>
237         <para/>
238         <para>
239         bitnum can be an array:
240         </para>
241         <programlisting role="example"><![CDATA[
242 bitcmp([0 0 0 0 0], 3:7)
243      ]]></programlisting>
244         <screen><![CDATA[
245 --> bitcmp([0 0 0 0 0], 3:7)
246  ans  =
247    7.   15.   31.   63.   127.
248 ]]></screen>
249         <para/>
250         <para>
251             bitnum can be > 52:
252         </para>
253         <programlisting role="example"><![CDATA[
254 format(22)
255 bitcmp(2^70, 65)
256 sum(2.^(13:64))   // 52 highest bits
257      ]]></programlisting>
258         <screen><![CDATA[
259 --> bitcmp(2^70, 65)
260  ans  =
261    36893488147419095040.
262
263 --> sum(2.^(13:64))
264  ans  =
265    36893488147419095040.
266 ]]></screen>
267         <para/>
268         <para>
269             Huge decimal numbers can be processed:
270         </para>
271         <programlisting role="example"><![CDATA[
272 format(22)
273 log2(1e100)
274 r = bitcmp(1e100, 333)
275 bitcmp(1e100) // bitnum = int(log2(x)) + 1 is used by default
276 bitcmp(r, 333)
277      ]]></programlisting>
278         <screen><![CDATA[
279 --> log2(1e100)
280  ans  =
281    332.19280948873625903
282
283 --> r = bitcmp(1e100, 333)
284  r  =
285    7.498005798264093D+99
286
287 --> bitcmp(1e100)  // bitnum = int(log2(x)) + 1 is used by default
288  ans  =
289    7.498005798264093D+99
290
291 --> bitcmp(r, 333)
292  ans  =
293    1.00000000000000D+100
294 ]]></screen>
295     </refsection>
296     <refsection role="see also">
297         <title>See Also</title>
298         <simplelist type="inline">
299             <member>
300                 <link linkend="bitxor">bitxor</link>
301             </member>
302             <member>
303                 <link linkend="bitget">bitget</link>
304             </member>
305             <member>
306                 <link linkend="minus">minus</link>
307             </member>
308         </simplelist>
309     </refsection>
310     <refsection role="history">
311         <title>History</title>
312         <revhistory>
313             <revision>
314                 <revnumber>6.1.1</revnumber>
315                 <revdescription>
316                     <itemizedlist>
317                         <listitem>
318                             Extension to 64 bit integers.
319                         </listitem>
320                         <listitem>
321                             Extension to all signed integers.
322                         </listitem>
323                         <listitem>
324                             Decimal positive integers > 2^52 up to 2^1024 = number_properties("huge")
325                             can now be processed, with bitnum up to 1024 instead of 52.
326                         </listitem>
327                         <listitem>
328                             bitnum is now optional as well for input decimal integers.
329                             It can actually be an array.
330                         </listitem>
331                     </itemizedlist>
332                 </revdescription>
333             </revision>
334         </revhistory>
335     </refsection>
336 </refentry>