bitget(u-int64) fixed & examples added
[scilab.git] / scilab / modules / elementary_functions / help / en_US / bitwise / bitget.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  *
4  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5  * Copyright (C) 2011 - DIGITEO - Michael Baudin
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2017 - 2020 - Samuel GOUGEON
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
19         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20         xmlns:scilab="http://www.scilab.org"
21         xml:id="bitget" xml:lang="en">
22     <refnamediv>
23         <refname>bitget</refname>
24         <refpurpose>Extracts from integers bits of given indices</refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             y = bitget(x, pos)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Parameters</title>
34         <variablelist>
35             <varlistentry>
36                 <term>x</term>
37                 <listitem>
38                     Scalar, vector, matrix or hypermatrix of positive decimal or encoded integers.
39                     <para/>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>pos</term>
44                 <listitem>
45                     Scalar, vector, matrix or hypermatrix of decimal or encoded integers in
46                     <literal>[1, bitmax]</literal> where <literal>bitmax</literal> is the
47                     maximal index of bits for the type of <varname>x</varname>: Indices of bits
48                     to be extracted. The bit #1 is the lightest one (2<superscript>0</superscript>).
49             <table>
50                 <tr><th>typeof(x)</th><th>bitmax</th><td>..</td><th>typeof(x)</th><th>bitmax</th></tr>
51                 <tr align="center"><td>int8  </td><td>7</td> <td>  </td><td>uint8</td><td>8</td></tr>
52                 <tr align="center"><td>int16 </td><td>15</td><td>  </td><td>uint16</td><td>16</td></tr>
53                 <tr align="center"><td>int32 </td><td>31</td><td>  </td><td>uint32</td><td>32</td></tr>
54                 <tr align="center"><td>int64 </td><td>63</td><td>  </td><td>uint64</td><td>64</td></tr>
55                 <tr align="center"><td>decimal</td><td>1024</td><td>  </td><td></td><td></td></tr>
56             </table>
57                     <para/>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>y</term>
62                 <listitem>
63                     <para>
64                         Scalar, vector, matrix or hypermatrix of 0 and 1 of the type of
65                         <varname>x</varname>. The sizes and contents of <varname>y</varname> are
66                         as follows:
67                     </para>
68                     <para>
69                         <emphasis role="bold">If <varname>x</varname> is a scalar</emphasis>:
70                         <itemizedlist>
71                             <listitem>
72                                 <varname>y</varname> has the sizes of <varname>pos</varname>
73                             </listitem>
74                             <listitem>
75                                 <literal>y(i,j,..)</literal> is the value of bit
76                                 #<literal>pos(i,j,..)</literal> of <varname>x</varname>.
77                             </listitem>
78                         </itemizedlist>
79                     </para>
80                     <para>
81                         <emphasis role="bold">If <varname>pos</varname> is a scalar</emphasis>:
82                         <itemizedlist>
83                             <listitem>
84                                 <varname>y</varname> has the sizes of <varname>x</varname>
85                             </listitem>
86                             <listitem>
87                                 <literal>y(i,j,..)</literal> is the value of the bit
88                                 #<literal>pos</literal> of <literal>x(i,j,..)</literal>.
89                             </listitem>
90                         </itemizedlist>
91                     </para>
92                     <para>
93                         <emphasis role="bold">If <varname>x</varname> and <varname>pos</varname>
94                         are arrays with identical sizes</emphasis>, the processing is element-wise:
95                         <itemizedlist>
96                             <listitem>
97                                 <varname>y</varname> has the sizes of <varname>x</varname>
98                                 and <varname>pos</varname>
99                             </listitem>
100                             <listitem>
101                                 <literal>y(i,j,..)</literal> is the value of the bit
102                                 #<literal>pos(i,j,..)</literal> of <literal>x(i,j,..)</literal>.
103                             </listitem>
104                         </itemizedlist>
105                     </para>
106                     <para>
107                         <emphasis role="bold">Otherwise</emphasis>:
108                         <itemizedlist>
109                             <listitem>
110                                 <varname>y</varname> is a matrix with
111                                 <literal>length(x)</literal> rows and
112                                 <literal>length(pos)</literal> columns.
113                             </listitem>
114                             <listitem>
115                                 <literal>y(i,j)</literal> is the value of the bit
116                                 #<literal>pos(j)</literal> of <literal>x(i)</literal>.
117                             </listitem>
118                         </itemizedlist>
119                     </para>
120                 </listitem>
121             </varlistentry>
122         </variablelist>
123     </refsection>
124     <refsection>
125         <title>Description</title>
126         <para>
127             <literal>bitget()</literal> scans chosen bits of the binary representation of some
128             positive integers <varname>x</varname>. It returns 0 for bits down, and 1 for bits up.
129         </para>
130         <para>
131             The result has the sizes of <varname>x</varname> or of <varname>pos</varname> or
132             of both inputs.
133         </para>
134         <para>
135             However, when both <varname>x</varname> and <varname>pos</varname> are non-scalar and
136             have mismatching sizes, the result <varname>y</varname> is a matrix ignoring the sizes
137             of <varname>x</varname>. Then, after reshaping <varname>y</varname> with
138             <literal>y = matrix(y, [size(x) -1])</literal>, the value of the bit #b of
139             <literal>x(i,..,k)</literal> is in <literal>y(i,..,k,b)</literal>.
140         </para>
141     </refsection>
142     <refsection>
143         <title>Examples</title>
144         <programlisting role="example"><![CDATA[
145 // 19 is (10011)_2
146 // The 2nd bit is 1 (starting from the end).
147 x = uint8(19);
148 pos = 2;
149 y = bitget(x,pos)
150 expected = 1;
151
152 // 13 is (1101)_2
153 dec2bin(13)
154 bitget(uint8(13),4:-1:1)
155    ]]></programlisting>
156         <para>
157             <emphasis role="bold">With encoded integers</emphasis>:
158         </para>
159         <programlisting role="example"><![CDATA[
160 b = [1 3 8 11 15];
161 x = sum(int16(2).^(b-1))
162 B = bitget(x, 1:15)
163 find(B)
164 typeof(B)
165    ]]></programlisting>
166         <screen><![CDATA[
167 --> b = [1 3 8 11 15];
168 --> x = sum(int16(2).^(b-1))
169  x  =
170   17541
171
172 --> B = bitget(x, 1:15)
173  B  =
174   1  0  1  0  0  0  0  1  0  0  1  0  0  0  1
175
176 --> find(B)
177  ans  =
178    1.   3.   8.   11.   15.
179
180 --> typeof(B)
181  ans  =
182   "int16"
183 ]]></screen>
184         <para>
185             <emphasis role="bold">
186                 With uint64 integers > 2<superscript>52</superscript>
187             </emphasis>:
188         </para>
189         <programlisting role="example"><![CDATA[
190 b = [1 12 23 34 45 53 64];
191 x = sum(uint64(2).^(b-1))
192 B = bitget(x, 1:64)
193 find(B)
194 typeof(B)
195      ]]></programlisting>
196         <screen><![CDATA[
197 --> b = [1 12 23 34 45 53 64];
198 --> x = sum(uint64(2).^(b-1))
199  x  =
200   9227893237262321665
201
202 --> B = bitget(x, 1:64)
203  B  =
204          column 1 to 32
205  1 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0
206
207          column 33 to 64
208  0 1 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 1
209
210 --> find(B)
211  ans  =
212    1.   12.   23.   34.   45.   53.   64.
213
214 --> typeof(B)
215  ans  =
216   "uint64"
217 ]]></screen>
218         <para>
219             <emphasis role="bold">
220                 With big decimal integers > 2<superscript>52</superscript>
221             </emphasis>:
222         </para>
223         <programlisting role="example"><![CDATA[
224 x = sum(2 .^([7 16 18 19 25 52 70]-1))
225 bitget(x,    [7 16 18 19 35 52 70 80])
226      ]]></programlisting>
227         <screen><![CDATA[
228 --> x = sum(2 .^([7 16 18 19 25 52 70]-1))
229  x  =
230    5.903D+20
231
232 --> bitget(x,    [7 16 18 19 35 52 70 80])
233  ans  =
234    Nan   Nan   1.   1.   0.   1.   1.   0.
235 ]]></screen>
236         <para>
237             <emphasis role="bold">x and pos are arrays with mismatching sizes:</emphasis>
238         </para>
239         <programlisting role="example"><![CDATA[
240 x = [ 39  6   62
241       8   14  29
242       4   64  12
243       44  39  50
244       52  12  39
245       5   4   29 ];
246 x = sum(2.^(x-1),2);
247 bitget(x, [5 8 12 39])
248       ]]></programlisting>
249          <screen><![CDATA[
250 --> bitget(x, [5 8 12 39])
251  ans  =
252    Nan   Nan   0.   1.
253    0.    1.    0.   0.
254    Nan   Nan   1.   0.
255    0.    0.    0.   1.
256    0.    0.    1.   1.
257    1.    0.    0.   0.
258 ]]></screen>
259     </refsection>
260     <refsection role="see also">
261         <title>See Also</title>
262         <simplelist type="inline">
263             <member>
264                 <link linkend="bitstring">bitstring</link>
265             </member>
266             <member>
267                 <link linkend="dec2bin">dec2bin</link>
268             </member>
269             <member>
270                 <link linkend="bitset">bitset</link>
271             </member>
272             <member>
273                 <link linkend="bitand">bitand</link>
274             </member>
275             <member>
276                 <link linkend="and_op">&amp;</link>
277             </member>
278         </simplelist>
279     </refsection>
280     <refsection role="history">
281         <title>History</title>
282         <revhistory>
283             <revision>
284                 <revnumber>6.1</revnumber>
285                 <revdescription>
286                     <itemizedlist>
287                         <listitem>
288                             Positive signed integers are now accepted.
289                         </listitem>
290                         <listitem>
291                             64 bits encoded integers are now accepted.
292                         </listitem>
293                         <listitem>
294                             For decimal integers, bits with index in [53, 1024] can now be retrieved.
295                         </listitem>
296                         <listitem>
297                             For decimal integers > 2<superscript>52</superscript>, querying bits
298                             below the <literal>%eps</literal> relative accuracy now returns
299                             <literal>NaN</literal> instead of 0.
300                         </listitem>
301                         <listitem>
302                             It is now possible to retrieve several bits from each component of
303                             an input array.
304                         </listitem>
305                     </itemizedlist>
306                 </revdescription>
307             </revision>
308         </revhistory>
309     </refsection>
310 </refentry>