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