<?xml version="1.0" encoding="UTF-8"?>
<!--
 *
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2011 - DIGITEO - Michael Baudin
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2017 - 2020 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
        xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
        xmlns:scilab="http://www.scilab.org"
        xml:id="bitget" xml:lang="en">
    <refnamediv>
        <refname>bitget</refname>
        <refpurpose>Extracts from integers bits of given indices</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            y = bitget(x, pos)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parameters</title>
        <variablelist>
            <varlistentry>
                <term>x</term>
                <listitem>
                    Scalar, vector, matrix or hypermatrix of positive decimal or encoded integers.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>pos</term>
                <listitem>
                    Scalar, vector, matrix or hypermatrix of decimal or encoded integers in
                    <literal>[1, bitmax]</literal> where <literal>bitmax</literal> is the
                    maximal index of bits for the type of <varname>x</varname>: Indices of bits
                    to be extracted. The bit #1 is the lightest one (2<superscript>0</superscript>).
            <table>
                <tr><th>typeof(x)</th><th>bitmax</th><td>..</td><th>typeof(x)</th><th>bitmax</th></tr>
                <tr align="center"><td>int8  </td><td>7</td> <td>  </td><td>uint8</td><td>8</td></tr>
                <tr align="center"><td>int16 </td><td>15</td><td>  </td><td>uint16</td><td>16</td></tr>
                <tr align="center"><td>int32 </td><td>31</td><td>  </td><td>uint32</td><td>32</td></tr>
                <tr align="center"><td>int64 </td><td>63</td><td>  </td><td>uint64</td><td>64</td></tr>
                <tr align="center"><td>decimal</td><td>1024</td><td>  </td><td></td><td></td></tr>
            </table>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                        Scalar, vector, matrix or hypermatrix of 0 and 1 of the type of
                        <varname>x</varname>. The sizes and contents of <varname>y</varname> are
                        as follows:
                    </para>
                    <para>
                        <emphasis role="bold">If <varname>x</varname> is a scalar</emphasis>:
                        <itemizedlist>
                            <listitem>
                                <varname>y</varname> has the sizes of <varname>pos</varname>
                            </listitem>
                            <listitem>
                                <literal>y(i,j,..)</literal> is the value of bit
                                #<literal>pos(i,j,..)</literal> of <varname>x</varname>.
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        <emphasis role="bold">If <varname>pos</varname> is a scalar</emphasis>:
                        <itemizedlist>
                            <listitem>
                                <varname>y</varname> has the sizes of <varname>x</varname>
                            </listitem>
                            <listitem>
                                <literal>y(i,j,..)</literal> is the value of the bit
                                #<literal>pos</literal> of <literal>x(i,j,..)</literal>.
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        <emphasis role="bold">If <varname>x</varname> and <varname>pos</varname>
                        are arrays with identical sizes</emphasis>, the processing is element-wise:
                        <itemizedlist>
                            <listitem>
                                <varname>y</varname> has the sizes of <varname>x</varname>
                                and <varname>pos</varname>
                            </listitem>
                            <listitem>
                                <literal>y(i,j,..)</literal> is the value of the bit
                                #<literal>pos(i,j,..)</literal> of <literal>x(i,j,..)</literal>.
                            </listitem>
                        </itemizedlist>
                    </para>
                    <para>
                        <emphasis role="bold">Otherwise</emphasis>:
                        <itemizedlist>
                            <listitem>
                                <varname>y</varname> is a matrix with
                                <literal>length(x)</literal> rows and
                                <literal>length(pos)</literal> columns.
                            </listitem>
                            <listitem>
                                <literal>y(i,j)</literal> is the value of the bit
                                #<literal>pos(j)</literal> of <literal>x(i)</literal>.
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>bitget()</literal> scans chosen bits of the binary representation of some
            positive integers <varname>x</varname>. It returns 0 for bits down, and 1 for bits up.
        </para>
        <para>
            The result has the sizes of <varname>x</varname> or of <varname>pos</varname> or
            of both inputs.
        </para>
        <para>
            However, when both <varname>x</varname> and <varname>pos</varname> are non-scalar and
            have mismatching sizes, the result <varname>y</varname> is a matrix ignoring the sizes
            of <varname>x</varname>. Then, after reshaping <varname>y</varname> with
            <literal>y = matrix(y, [size(x) -1])</literal>, the value of the bit #b of
            <literal>x(i,..,k)</literal> is in <literal>y(i,..,k,b)</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// 19 is (10011)_2
// The 2nd bit is 1 (starting from the end).
x = uint8(19);
pos = 2;
y = bitget(x,pos)
expected = 1;

// 13 is (1101)_2
dec2bin(13)
bitget(uint8(13),4:-1:1)
   ]]></programlisting>
        <para>
            <emphasis role="bold">With encoded integers</emphasis>:
        </para>
        <programlisting role="example"><![CDATA[
b = [1 3 8 11 15];
x = sum(int16(2).^(b-1))
B = bitget(x, 1:15)
find(B)
typeof(B)
   ]]></programlisting>
        <screen><![CDATA[
--> b = [1 3 8 11 15];
--> x = sum(int16(2).^(b-1))
 x  =
  17541

--> B = bitget(x, 1:15)
 B  =
  1  0  1  0  0  0  0  1  0  0  1  0  0  0  1

--> find(B)
 ans  =
   1.   3.   8.   11.   15.

--> typeof(B)
 ans  =
  "int16"
]]></screen>
        <para>
            <emphasis role="bold">
                With uint64 integers > 2<superscript>52</superscript>
            </emphasis>:
        </para>
        <programlisting role="example"><![CDATA[
b = [1 12 23 34 45 53 64];
x = sum(uint64(2).^(b-1))
B = bitget(x, 1:64)
find(B)
typeof(B)
     ]]></programlisting>
        <screen><![CDATA[
--> b = [1 12 23 34 45 53 64];
--> x = sum(uint64(2).^(b-1))
 x  =
  9227893237262321665

--> B = bitget(x, 1:64)
 B  =
         column 1 to 32
 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

         column 33 to 64
 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

--> find(B)
 ans  =
   1.   12.   23.   34.   45.   53.   64.

--> typeof(B)
 ans  =
  "uint64"
]]></screen>
        <para>
            <emphasis role="bold">
                With big decimal integers > 2<superscript>52</superscript>
            </emphasis>:
        </para>
        <programlisting role="example"><![CDATA[
x = sum(2 .^([7 16 18 19 25 52 70]-1))
bitget(x,    [7 16 18 19 35 52 70 80])
     ]]></programlisting>
        <screen><![CDATA[
--> x = sum(2 .^([7 16 18 19 25 52 70]-1))
 x  =
   5.903D+20

--> bitget(x,    [7 16 18 19 35 52 70 80])
 ans  =
   Nan   Nan   1.   1.   0.   1.   1.   0.
]]></screen>
        <para>
            <emphasis role="bold">x and pos are arrays with mismatching sizes:</emphasis>
        </para>
        <programlisting role="example"><![CDATA[
x = [ 39  6   62
      8   14  29
      4   64  12
      44  39  50
      52  12  39
      5   4   29 ];
x = sum(2.^(x-1),2);
bitget(x, [5 8 12 39])
      ]]></programlisting>
         <screen><![CDATA[
--> bitget(x, [5 8 12 39])
 ans  =
   Nan   Nan   0.   1.
   0.    1.    0.   0.
   Nan   Nan   1.   0.
   0.    0.    0.   1.
   0.    0.    1.   1.
   1.    0.    0.   0.
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="bitstring">bitstring</link>
            </member>
            <member>
                <link linkend="dec2bin">dec2bin</link>
            </member>
            <member>
                <link linkend="bitset">bitset</link>
            </member>
            <member>
                <link linkend="bitand">bitand</link>
            </member>
            <member>
                <link linkend="and_op">&amp;</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.1</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            Positive signed integers are now accepted.
                        </listitem>
                        <listitem>
                            64 bits encoded integers are now accepted.
                        </listitem>
                        <listitem>
                            For decimal integers, bits with index in [53, 1024] can now be retrieved.
                        </listitem>
                        <listitem>
                            For decimal integers > 2<superscript>52</superscript>, querying bits
                            below the <literal>%eps</literal> relative accuracy now returns
                            <literal>NaN</literal> instead of 0.
                        </listitem>
                        <listitem>
                            It is now possible to retrieve several bits from each component of
                            an input array.
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
