bitget(u-int64) fixed & examples added
[scilab.git] / scilab / modules / elementary_functions / help / en_US / bitwise / bitget.xml
index ea2aa72..7ad0377 100644 (file)
@@ -3,9 +3,8 @@
  *
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2011 - DIGITEO - Michael Baudin
- * Copyright (C) 2017 - Samuel GOUGEON
- *
  * 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.
             <varlistentry>
                 <term>x</term>
                 <listitem>
-                    <para>
-                        Scalar, vector, matrix or hypermatrix of positive decimal or encoded integers.
-                    </para>
+                    Scalar, vector, matrix or hypermatrix of positive decimal or encoded integers.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>pos</term>
                 <listitem>
-                    <para>
-                        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>).
+                    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>uint16</td><td>64</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>
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
                         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>
-                                <para>
-                                If <varname>x</varname> is a scalar:
-                                <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>
+                                <varname>y</varname> has the sizes of <varname>x</varname>
+                                and <varname>pos</varname>
                             </listitem>
                             <listitem>
-                                <para>
-                                If <varname>pos</varname> is a scalar:
-                                <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>
+                                <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>
-                                <para>
-                                If <varname>x</varname> and <varname>pos</varname> are arrays with
-                                identical sizes, 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>
+                                <varname>y</varname> is a matrix with
+                                <literal>length(x)</literal> rows and
+                                <literal>length(pos)</literal> columns.
                             </listitem>
                             <listitem>
-                                <para>Otherwise:
-                                <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>
+                                <literal>y(i,j)</literal> is the value of the bit
+                                #<literal>pos(j)</literal> of <literal>x(i)</literal>.
                             </listitem>
                         </itemizedlist>
                     </para>
         <programlisting role="example"><![CDATA[
 // 19 is (10011)_2
 // The 2nd bit is 1 (starting from the end).
-x=uint8(19);
-pos=2;
+x = uint8(19);
+pos = 2;
 y = bitget(x,pos)
 expected = 1;
 
@@ -166,20 +154,76 @@ dec2bin(13)
 bitget(uint8(13),4:-1:1)
    ]]></programlisting>
         <para>
-        <emphasis role="bold">With arrays and encoded integers:</emphasis>:
+            <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>:
+            <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>
+     ]]></programlisting>
         <screen><![CDATA[
 --> x = sum(2 .^([7 16 18 19 25 52 70]-1))
  x  =
@@ -190,7 +234,7 @@ bitget(x,    [7 16 18 19 35 52 70 80])
    Nan   Nan   1.   1.   0.   1.   1.   0.
 ]]></screen>
         <para>
-        <emphasis role="bold">x and pos are arrays with mismatching sizes:</emphasis>
+            <emphasis role="bold">x and pos are arrays with mismatching sizes:</emphasis>
         </para>
         <programlisting role="example"><![CDATA[
 x = [ 39  6   62
@@ -201,8 +245,8 @@ x = [ 39  6   62
       5   4   29 ];
 x = sum(2.^(x-1),2);
 bitget(x, [5 8 12 39])
-   ]]></programlisting>
-   <screen><![CDATA[
+      ]]></programlisting>
+         <screen><![CDATA[
 --> bitget(x, [5 8 12 39])
  ans  =
    Nan   Nan   0.   1.
@@ -241,7 +285,7 @@ bitget(x, [5 8 12 39])
                 <revdescription>
                     <itemizedlist>
                         <listitem>
-                            Positive unsigned integers are now accepted.
+                            Positive signed integers are now accepted.
                         </listitem>
                         <listitem>
                             64 bits encoded integers are now accepted.