← Back to branch summary

~vcs-imports/scilab/master

« back to all changes in this revision

Viewing changes to scilab/modules/elementary_functions/help/en_US/bitwise/bitget.xml

  • Committer: Clément DAVID
  • Author(s): Samuel GOUGEON
  • Date: 2018-03-15 16:48:11 UTC
  • Revision ID: git-v1:7fe1d12b2b08e428047fd00bbc56534f222e12a4
* bug 15271: bitget() needed being upgraded

 * http://bugzilla.scilab.org/2694
 * http://bugzilla.scilab.org/15271
 a) Positive signed encoded integers are now supported (bug 2694)
 b) new uint64 and int64 integers are now supported
 c) Decimal numbers: bits indices > 52 are now supported (up to 1024).
 d) For decimal numbers x > 2^52 with pos < log2(x)-52, %nan is now
    returned instead of 0.
 e) It is now possible to query the value of more than 1 bit from each
    component of an array.

Change-Id: I2f0d1dd8137b0d8ea89589218188c88ecc994b2a

Show diffs side-by-side

added added

removed removed

Lines of Context:
scilab/modules/elementary_functions/help/en_US/bitwise/bitget.xml
3
3
 *
4
4
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5
5
 * Copyright (C) 2011 - DIGITEO - Michael Baudin
 
6
 * Copyright (C) 2017 - Samuel GOUGEON
6
7
 *
7
8
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
8
9
 *
14
15
 * along with this program.
15
16
 *
16
17
 -->
17
 
<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">
 
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">
18
23
    <refnamediv>
19
24
        <refname>bitget</refname>
20
 
        <refpurpose>bit at specified position</refpurpose>
 
25
        <refpurpose>Extracts from integers bits of given indices</refpurpose>
21
26
    </refnamediv>
22
27
    <refsynopsisdiv>
23
28
        <title>Syntax</title>
29
34
        <title>Parameters</title>
30
35
        <variablelist>
31
36
            <varlistentry>
32
 
                <term>x :</term>
33
 
                <listitem>
34
 
                    <para>
35
 
                        a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
36
 
                        or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
37
 
                        or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>).
38
 
                        Must contain positive integer values.
39
 
                    </para>
40
 
                </listitem>
41
 
            </varlistentry>
42
 
            <varlistentry>
43
 
                <term>pos :</term>
44
 
                <listitem>
45
 
                    <para>
46
 
                        a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
47
 
                        or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
48
 
                        or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>).
49
 
                        The input <varname>pos</varname> must be in the range 1, 2, ..., <literal>bitmax</literal>
50
 
                        where <literal>bitmax</literal> is the maximum number of bits in <varname>x</varname>.
51
 
                        Must contain positive integer values.
52
 
                    </para>
53
 
                </listitem>
54
 
            </varlistentry>
55
 
            <varlistentry>
56
 
                <term>y :</term>
57
 
                <listitem>
58
 
                    <para>
59
 
                        a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
60
 
                        or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
61
 
                        or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers.
 
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>
62
131
                    </para>
63
132
                </listitem>
64
133
            </varlistentry>
67
136
    <refsection>
68
137
        <title>Description</title>
69
138
        <para>
70
 
            Given an unsigned integer <varname>x</varname>, this function returns an unsigned integer <varname>y</varname>
71
 
            (<literal>0</literal> or <literal>1</literal>) which is the bit number <varname>pos</varname> from the representation binary of <varname>x</varname>.
 
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>.
72
152
        </para>
73
153
    </refsection>
74
154
    <refsection>
84
164
// 13 is (1101)_2
85
165
dec2bin(13)
86
166
bitget(uint8(13),4:-1:1)
87
 
 
88
 
// The input x can be a positive double
89
 
bitget(13,4:-1:1)
90
 
   ]]></programlisting>
 
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  8  4  44  52  5  6  14  64 39  12  4  62  29  12  50  39  29];
 
197
x = matrix(x,2,3,3);
 
198
// (:,:,1)
 
199
//   39.   4.    52.
 
200
//   8.    44.   5.
 
201
// (:,:,2)
 
202
//   6.    64.   12.
 
203
//   14.   39.   4.
 
204
// (:,:,3)
 
205
//   62.   12.   39.
 
206
//   29.   50.   29.
 
207
x = sum(2.^(x-1),3);
 
208
bitget(x, [5 8 12 39])
 
209
   ]]></programlisting>
 
210
   <screen><![CDATA[
 
211
--> bitget(x, [5 8 12 39])
 
212
 ans  =
 
213
   Nan   Nan   0.   1.
 
214
   0.    1.    0.   0.
 
215
   Nan   Nan   1.   0.
 
216
   0.    0.    0.   1.
 
217
   0.    0.    1.   1.
 
218
   1.    0.    0.   0.
 
219
]]></screen>
 
220
    </refsection>
 
221
    <refsection role="see also">
 
222
        <title>See Also</title>
 
223
        <simplelist type="inline">
 
224
            <member>
 
225
                <link linkend="bitset">bitset</link>
 
226
            </member>
 
227
            <member>
 
228
                <link linkend="bitand">bitand</link>
 
229
            </member>
 
230
            <member>
 
231
                <link linkend="dec2bin">dec2bin</link>
 
232
            </member>
 
233
            <member>
 
234
                <link linkend="and_op">&amp;</link>
 
235
            </member>
 
236
        </simplelist>
 
237
    </refsection>
 
238
    <refsection role="history">
 
239
        <title>History</title>
 
240
        <revhistory>
 
241
            <revision>
 
242
                <revnumber>6.1</revnumber>
 
243
                <revdescription>
 
244
                    <itemizedlist>
 
245
                        <listitem>
 
246
                            Positive unsigned integers are now accepted.
 
247
                        </listitem>
 
248
                        <listitem>
 
249
                            64 bits encoded integers are now accepted.
 
250
                        </listitem>
 
251
                        <listitem>
 
252
                            For decimal integers, bits with index in [53, 1024] can now be retrieved.
 
253
                        </listitem>
 
254
                        <listitem>
 
255
                            For decimal integers > 2<superscript>52</superscript>, querying bits
 
256
                            below the <literal>%eps</literal> relative accuracy now returns
 
257
                            <literal>NaN</literal> instead of 0.
 
258
                        </listitem>
 
259
                        <listitem>
 
260
                            It is now possible to retrieve several bits from each component of
 
261
                            an input array.
 
262
                        </listitem>
 
263
                    </itemizedlist>
 
264
                </revdescription>
 
265
            </revision>
 
266
        </revhistory>
91
267
    </refsection>
92
268
</refentry>