bitget(u-int64) fixed & examples added
[scilab.git] / scilab / modules / elementary_functions / help / ru_RU / 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="ru">
23     <refnamediv>
24         <refname>bitget</refname>
25         <refpurpose>Извлекает из целых чисел биты по указанным индексам</refpurpose>
26     </refnamediv>
27     <refsynopsisdiv>
28         <title>Синтаксис</title>
29         <synopsis>
30             y = bitget(x, pos)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Аргументы</title>
35         <variablelist>
36             <varlistentry>
37                 <term>x</term>
38                 <listitem>
39                     Скаляр, вектор, матрица или гиперматрица положительных десятичных или
40                     кодированных целых чисел.
41                     <para/>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>pos</term>
46                 <listitem>
47                     Скаляр, вектор, матрица или гиперматрица десятичных или кодированных целых чисел в
48                     <literal>[1, bitmax]</literal>, где <literal>bitmax</literal> - это максимальный
49                     индекс битов для типа переменной <varname>x</varname>: индексы битов, которые
50                     следует извлечь. Бит №1 - это наименьший бит  (2<superscript>0</superscript>).
51             <table>
52                 <tr><th>typeof(x)</th><th>bitmax</th><td>..</td><th>typeof(x)</th><th>bitmax</th></tr>
53                 <tr align="center"><td>int8  </td><td>7</td> <td>  </td><td>uint8</td><td>8</td></tr>
54                 <tr align="center"><td>int16 </td><td>15</td><td>  </td><td>uint16</td><td>16</td></tr>
55                 <tr align="center"><td>int32 </td><td>31</td><td>  </td><td>uint32</td><td>32</td></tr>
56                 <tr align="center"><td>int64 </td><td>63</td><td>  </td><td>uint64</td><td>64</td></tr>
57                 <tr align="center"><td>десятичное число</td><td>1024</td><td>  </td><td></td><td></td></tr>
58             </table>
59                     <para/>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>y</term>
64                 <listitem>
65                     <para>
66                         Скаляр, вектор, матрица или гиперматрица из 0 и 1 типа переменной
67                         <varname>x</varname>. Размеры и содержимое <varname>y</varname> следующие:
68                     </para>
69                     <para>
70                         <emphasis role="bold">Если <varname>x</varname> скаляр</emphasis>:
71                         <itemizedlist>
72                             <listitem>
73                                 <varname>y</varname> имеет размеры <varname>pos</varname>
74                             </listitem>
75                             <listitem>
76                                 <literal>y(i,j,..)</literal> - это значение бита
77                                 №<literal>pos(i,j,..)</literal> переменной <varname>x</varname>.
78                             </listitem>
79                         </itemizedlist>
80                     </para>
81                     <para>
82                         <emphasis role="bold">Если <varname>pos</varname> скаляр</emphasis>:
83                         <itemizedlist>
84                             <listitem>
85                                 <varname>y</varname> имеет размеры <varname>x</varname>
86                             </listitem>
87                             <listitem>
88                                 <literal>y(i,j,..)</literal> - это значение бита
89                                 №<literal>pos</literal> в <literal>x(i,j,..)</literal>.
90                             </listitem>
91                         </itemizedlist>
92                     </para>
93                     <para>
94                         <emphasis role="bold">Если <varname>x</varname> и <varname>pos</varname>
95                         являются  массивами одинаковых размеров</emphasis>,
96                         то обработка идёт поэлементно:
97                         <itemizedlist>
98                             <listitem>
99                                 <varname>y</varname> имеет размеры <varname>x</varname>
100                                 и <varname>pos</varname>
101                             </listitem>
102                             <listitem>
103                                 <literal>y(i,j,..)</literal> - это значение бита
104                                 №<literal>pos(i,j,..)</literal> в <literal>x(i,j,..)</literal>.
105                             </listitem>
106                         </itemizedlist>
107                     </para>
108                     <para>
109                         <emphasis role="bold">В противном случае</emphasis>:
110                         <itemizedlist>
111                             <listitem>
112                                 <varname>y</varname> - это матрица, у которой
113                                 <literal>length(x)</literal> строк и
114                                 <literal>length(pos)</literal> столбцов.
115                             </listitem>
116                             <listitem>
117                                 <literal>y(i,j)</literal> - это значение бита
118                                 №<literal>pos(j)</literal> в <literal>x(i)</literal>.
119                             </listitem>
120                         </itemizedlist>
121                     </para>
122                 </listitem>
123             </varlistentry>
124         </variablelist>
125     </refsection>
126     <refsection>
127         <title>Описание</title>
128         <para>
129             <literal>bitget()</literal> сканирует выбранные биты двоичного представления неких
130             положительных целых чисел <varname>x</varname>.
131             Эта функция возвращает 0 для снятых битов и 1 для взведённых битов.
132         </para>
133         <para>
134            Результат имеет размеры <varname>x</varname> или <varname>pos</varname> или обеих входных
135            переменных.
136         </para>
137         <para>
138             Однако, если и <varname>x</varname> и <varname>pos</varname> являются нескалярами и
139             имеют несовпадающие размеры, то результат <varname>y</varname> является матрицей, игнорирующей
140             размеры <varname>x</varname>. Тогда, после изменения размеров <varname>y</varname>
141             с помощью <literal>y = matrix(y, [size(x) -1])</literal>, значение бита №b в <literal>x(i,..,k)</literal>
142             будет находиться в <literal>y(i,..,k,b)</literal>.
143         </para>
144     </refsection>
145     <refsection>
146         <title>Примеры</title>
147         <programlisting role="example"><![CDATA[
148 // 19 это (10011)_2
149 // Второй бит равен1 (начиная с конца).
150 x=uint8(19);
151 pos=2;
152 y = bitget(x,pos)
153 expected = 1;
154 // 13 это (1101)_2
155 dec2bin(13)
156 bitget(uint8(13),4:-1:1)
157    ]]></programlisting>
158         <para>
159             <emphasis role="bold">С кодированными целыми числами</emphasis>:
160         </para>
161         <programlisting role="example"><![CDATA[
162 b = [1 3 8 11 15];
163 x = sum(int16(2).^(b-1))
164 B = bitget(x, 1:15)
165 find(B)
166 typeof(B)
167    ]]></programlisting>
168         <screen><![CDATA[
169 --> b = [1 3 8 11 15];
170 --> x = sum(int16(2).^(b-1))
171  x  =
172   17541
173
174 --> B = bitget(x, 1:15)
175  B  =
176   1  0  1  0  0  0  0  1  0  0  1  0  0  0  1
177
178 --> find(B)
179  ans  =
180    1.   3.   8.   11.   15.
181
182 --> typeof(B)
183  ans  =
184   "int16"
185 ]]></screen>
186         <para>
187             <emphasis role="bold">
188                 С целыми числами типа uint64 больше 2<superscript>52</superscript>
189             </emphasis>:
190         </para>
191         <programlisting role="example"><![CDATA[
192 b = [1 12 23 34 45 53 64];
193 x = sum(uint64(2).^(b-1))
194 B = bitget(x, 1:64)
195 find(B)
196 typeof(B)
197      ]]></programlisting>
198         <screen><![CDATA[
199 --> b = [1 12 23 34 45 53 64];
200 --> x = sum(uint64(2).^(b-1))
201  x  =
202   9227893237262321665
203
204 --> B = bitget(x, 1:64)
205  B  =
206          column 1 to 32
207  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
208
209          column 33 to 64
210  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
211
212 --> find(B)
213  ans  =
214    1.   12.   23.   34.   45.   53.   64.
215
216 --> typeof(B)
217  ans  =
218   "uint64"
219 ]]></screen>
220         <para>
221         <emphasis role="bold">С большими десятичными целыми числами больше 2<superscript>52</superscript></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 и pos являются массивами несовпадающих размеров:</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>Смотрите также</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>История</title>
282         <revhistory>
283             <revision>
284                 <revnumber>6.1</revnumber>
285                 <revdescription>
286                     <itemizedlist>
287                         <listitem>
288                             Теперь принимаются положительные знаковые целые числа.
289                         </listitem>
290                         <listitem>
291                             Теперь принимаются 64-битные кодированные целые числа.
292                         </listitem>
293                         <listitem>
294                             Теперь для десятичных целых чисел можно получать биты с индексами в
295                             диапазоне [53, 1024].
296                         </listitem>
297                         <listitem>
298                             Для десятичных целых чисел > 2<superscript>52</superscript> опрос битов
299                           менее относительной точности <literal>%eps</literal> теперь возвращает
300                           <literal>NaN</literal> вместо 0.
301                         </listitem>
302                         <listitem>
303                             Теперь можно получить несколько битов от каждого элемента входного массива.
304                         </listitem>
305                     </itemizedlist>
306                 </revdescription>
307             </revision>
308         </revhistory>
309     </refsection>
310 </refentry>