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>