3a985faf27962ecbb71b333c00db67742a7f019a
[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                     <para>
40                         Скаляр, вектор, матрица или гиперматрица положительных десятичных или
41                         кодированных целых чисел.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>pos</term>
47                 <listitem>
48                     <para>
49                         Скаляр, вектор, матрица или гиперматрица десятичных или кодированных целых чисел в
50                         <literal>[1, bitmax]</literal>, где <literal>bitmax</literal> - это максимальный
51                         индекс битов для типа переменной <varname>x</varname>: индексы битов, которые
52                         следует извлечь. Бит №1 - это наименьший бит  (2<superscript>0</superscript>).
53             <table>
54                 <tr><th>typeof(x)</th><th>bitmax</th><td>..</td><th>typeof(x)</th><th>bitmax</th></tr>
55                 <tr align="center"><td>int8  </td><td>7</td> <td>  </td><td>uint8</td><td>8</td></tr>
56                 <tr align="center"><td>int16 </td><td>15</td><td>  </td><td>uint16</td><td>16</td></tr>
57                 <tr align="center"><td>int32 </td><td>31</td><td>  </td><td>uint32</td><td>32</td></tr>
58                 <tr align="center"><td>int64 </td><td>63</td><td>  </td><td>uint16</td><td>64</td></tr>
59                 <tr align="center"><td>десятичное число</td><td>1024</td><td>  </td><td></td><td></td></tr>
60             </table>
61                     </para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>y</term>
66                 <listitem>
67                     <para>
68                         Скаляр, вектор, матрица или гиперматрица из 0 и 1 типа переменной
69                         <varname>x</varname>. Размеры и содержимое <varname>y</varname> следующие:
70                         <itemizedlist>
71                             <listitem>
72                                 <para>
73                                 Если <varname>x</varname> скаляр:
74                                 <itemizedlist>
75                                     <listitem>
76                                         <varname>y</varname> имеет размеры <varname>pos</varname>
77                                     </listitem>
78                                     <listitem>
79                                         <literal>y(i,j,..)</literal> - это значение бита
80                                         №<literal>pos(i,j,..)</literal> переменной <varname>x</varname>.
81                                     </listitem>
82                                 </itemizedlist>
83                                 </para>
84                             </listitem>
85                             <listitem>
86                                 <para>
87                                 Если <varname>pos</varname> скаляр:
88                                 <itemizedlist>
89                                     <listitem>
90                                         <varname>y</varname> имеет размеры <varname>x</varname>
91                                     </listitem>
92                                     <listitem>
93                                         <literal>y(i,j,..)</literal> - это значение бита
94                                         №<literal>pos</literal> в <literal>x(i,j,..)</literal>.
95                                     </listitem>
96                                 </itemizedlist>
97                                 </para>
98                             </listitem>
99                             <listitem>
100                                 <para>
101                                 Если <varname>x</varname> и <varname>pos</varname> являются  массивами
102                                 одинаковых размеров, то обработка идёт поэлементно:
103                                 <itemizedlist>
104                                     <listitem>
105                                         <varname>y</varname> имеет размеры <varname>x</varname>
106                                         и <varname>pos</varname>
107                                     </listitem>
108                                     <listitem>
109                                         <literal>y(i,j,..)</literal> - это значение бита
110                                         №<literal>pos(i,j,..)</literal> в <literal>x(i,j,..)</literal>.
111                                     </listitem>
112                                 </itemizedlist>
113                                 </para>
114                             </listitem>
115                             <listitem>
116                                 <para>В противном случае:
117                                 <itemizedlist>
118                                     <listitem>
119                                         <varname>y</varname> - это матрица, у которой
120                                         <literal>length(x)</literal> строк и
121                                         <literal>length(pos)</literal> столбцов.
122                                     </listitem>
123                                     <listitem>
124                                         <literal>y(i,j)</literal> - это значение бита
125                                         №<literal>pos(j)</literal> в <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>Описание</title>
138         <para>
139             <literal>bitget()</literal> сканирует выбранные биты двоичного представления неких
140             положительных целых чисел <varname>x</varname>.
141             Эта функция возвращает 0 для снятых битов и 1 для взведённых битов.
142         </para>
143         <para>
144            Результат имеет размеры <varname>x</varname> или <varname>pos</varname> или обеих входных
145            переменных.
146         </para>
147         <para>
148             Однако, если и <varname>x</varname> и <varname>pos</varname> являются нескалярами и
149             имеют несовпадающие размеры, то результат <varname>y</varname> является матрицей, игнорирующей
150             размеры <varname>x</varname>. Тогда, после изменения размеров <varname>y</varname>
151             с помощью <literal>y = matrix(y, [size(x) -1])</literal>, значение бита №b в <literal>x(i,..,k)</literal>
152             будет находиться в <literal>y(i,..,k,b)</literal>.
153         </para>
154     </refsection>
155     <refsection>
156         <title>Примеры</title>
157         <programlisting role="example"><![CDATA[
158 // 19 это (10011)_2
159 // Второй бит равен1 (начиная с конца).
160 x=uint8(19);
161 pos=2;
162 y = bitget(x,pos)
163 expected = 1;
164 // 13 это (1101)_2
165 dec2bin(13)
166 bitget(uint8(13),4:-1:1)
167    ]]></programlisting>
168         <para>
169         <emphasis role="bold">С массивами и кодированными целыми числами:</emphasis>:
170         </para>
171         <programlisting role="example"><![CDATA[
172    ]]></programlisting>
173         <screen><![CDATA[
174 ]]></screen>
175         <para>
176         <emphasis role="bold">С большими десятичными целыми числами > 2<superscript>52</superscript></emphasis>:
177         </para>
178         <programlisting role="example"><![CDATA[
179 x = sum(2 .^([7 16 18 19 25 52 70]-1))
180 bitget(x,    [7 16 18 19 35 52 70 80])
181    ]]></programlisting>
182         <screen><![CDATA[
183 --> x = sum(2 .^([7 16 18 19 25 52 70]-1))
184  x  =
185    5.903D+20
186
187 --> bitget(x,    [7 16 18 19 35 52 70 80])
188  ans  =
189    Nan   Nan   1.   1.   0.   1.   1.   0.
190 ]]></screen>
191         <para>
192         <emphasis role="bold">x и pos являются массивами несовпадающих размеров:</emphasis>
193         </para>
194         <programlisting role="example"><![CDATA[
195 x = [ 39  6   62
196       8   14  29
197       4   64  12
198       44  39  50
199       52  12  39
200       5   4   29 ];
201 x = sum(2.^(x-1),2);
202 bitget(x, [5 8 12 39])
203    ]]></programlisting>
204    <screen><![CDATA[
205 --> bitget(x, [5 8 12 39])
206  ans  =
207    Nan   Nan   0.   1.
208    0.    1.    0.   0.
209    Nan   Nan   1.   0.
210    0.    0.    0.   1.
211    0.    0.    1.   1.
212    1.    0.    0.   0.
213 ]]></screen>
214     </refsection>
215     <refsection role="see also">
216         <title>Смотрите также</title>
217         <simplelist type="inline">
218             <member>
219                 <link linkend="bitstring">bitstring</link>
220             </member>
221             <member>
222                 <link linkend="dec2bin">dec2bin</link>
223             </member>
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="and_op">&amp;</link>
232             </member>
233         </simplelist>
234     </refsection>
235     <refsection role="history">
236         <title>История</title>
237         <revhistory>
238             <revision>
239                 <revnumber>6.1</revnumber>
240                 <revdescription>
241                     <itemizedlist>
242                         <listitem>
243                             Теперь принимаются положительные беззнаковые целые числа.
244                         </listitem>
245                         <listitem>
246                             Теперь принимаются 64-битные кодированные целые числа.
247                         </listitem>
248                         <listitem>
249                             Теперь для десятичных целых чисел можно получать биты с индексами в
250                             диапазоне [53, 1024].
251                         </listitem>
252                         <listitem>
253                             Для десятичных целых чисел > 2<superscript>52</superscript> опрос битов
254                           менее относительной точности <literal>%eps</literal> теперь возвращает
255                           <literal>NaN</literal> вместо 0.
256                         </listitem>
257                         <listitem>
258                             Теперь можно получить несколько битов от каждого элемента входного массива.
259                         </listitem>
260                     </itemizedlist>
261                 </revdescription>
262             </revision>
263         </revhistory>
264     </refsection>
265 </refentry>