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>