<?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) 2019 - 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="bitset" xml:lang="ru">
    <refnamediv>
        <refname>bitset</refname>
        <refpurpose>устанавливает в целых числах биты по указанным индексам</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
            y = bitset(x, bitInd)
            y = bitset(x, bitInd, bitVal)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Параметры</title>
        <variablelist>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>
                        положительные десятичные или кодированные целые числа (поддерживаются все типы целых чисел),
                        в которых нужно установить биты. Поддерживаемые размеры: скаляр, вектор, матрица, гиперматрица.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>bitInd</term>
                <listitem>
                    <para>
                        Индексы битов, которые должны быть установлены: массив положительных десятичных или кодированных
                        целых чисел (поддерживаются все типы целых чисел), чьи значения находятся в интервале
                        <literal>[1 bitmax]</literal>, где <varname>bitmax</varname> - это максимальный индекс битов для
                        типа <varname>x</varname>.
                        Бит №1 - самый младший (2<superscript>0</superscript>).
            <table style="padding:0px">
                <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>decimal</td><td>1024</td><td>  </td><td></td><td></td></tr>
            </table>
                    </para>
                    <para>
                        <itemizedlist>
                            <listitem>
                                <para>
                                  Если размер <varname>bitInd</varname> совпадает с размером <varname>x</varname>, то
                                  выполняется поэлементная обработка: для каждого индекса <literal>i</literal> в
                                  <varname>x</varname> бит №<literal>bitInd(i)</literal> устанавливается в <literal>x(i)</literal>.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                Если <varname>x</varname> имеет <literal>N</literal> размерностей и первые <literal>N</literal>
                                размерностей <varname>bitInd</varname> совпадают с размерностями <varname>x</varname>, и
                                <varname>bitInd</varname> имеет <literal>N+1</literal> размерностей, то для каждого
                                <literal>x(i1,i2,..iN)</literal> будут установлены все его биты
                                <literal>№bitInd(i1,i2,..iN, :)</literal>.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                В противном случае: <varname>bitInd</varname> должен быть вектором длиной&lt;=
                                <varname>bitmax</varname>. Тогда все биты, указанные в <varname>bitInd</varname>, устанавливаются
                                во всех элементах <varname>x</varname>.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>bitVal</term>
                <listitem>
                    <para>
                        Массив значений 0 или 1 в виде десятичных или кодированных целых чисел (поддерживаются
                        все типы целых чисел): значения в которые соответствующие биты должны быть установлены.
                        <varname>bitVal</varname> либо имеет размер <varname>bitInd</varname>, либо является скаляром
                        (тогда одно и то же значение используется для всех битов).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>
                        Обработанный <varname>x</varname> с тем же размером и типом данных (и типом целых чисел), что и
                        <varname>x</varname>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
           Устанавливает биты <varname>x</varname>, указанные с помощью <varname>bitInd</varname> либо в 1, либо в
           указанные значения <varname>bitVal</varname>.
        </para>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <para>
           Установка одного или нескольких битов в скаляре:
        </para>
        <programlisting role="example"><![CDATA[
n = int8(20);
ns = bitset(n, [1 3 6]) // Установка битов №1 №3 №6 (в 1, по умолчанию)
bitget([n ns], 1:7)     // содержимое битов до/после установки

ns = bitset(n, [1 3 6], [1 0 1]) // в явно указанные значения битов
bitget([n ns], 1:7)
   ]]></programlisting>
   <screen><![CDATA[
--> n = int8(20);
--> ns = bitset(n, [1 3 6]) // Установка битов №1 №3 №6 (в 1, по умолчанию)
 ns  =
  53

--> bitget([n ns], 1:7)     // содержимое битов до/после установки
 ans  =
  0  0  1  0  1  0  0
  1  0  1  0  1  1  0

--> ns = bitset(n, [1 3 6], [1 0 1]) // в явно указанные значения битов
 ns  =
  49

--> bitget([n ns], 1:7)
 ans  =
  0  0  1  0  1  0  0
  1  0  0  0  1  1  0
]]></screen>
        <para>
        Установка одних и тех же битов в одно и тоже значение во всех входных элементах:
        </para>
        <programlisting role="example"><![CDATA[
n = uint16([28  59; 23  19])
ns = bitset(n, [3 5], [1 0])
bitget(n, 1:8)
bitget(ns,1:8)
   ]]></programlisting>
   <screen><![CDATA[
--> n = uint16([28  59; 23  19])
 n  =
  28  59
  23  19

--> ns = bitset(n, [3 5], [1 0])
 ns  =
  12  47
   7   7

--> bitget(n, 1:8)
 ans  =
  0  0  1  1  1  0  0  0
  1  1  1  0  1  0  0  0
  1  1  0  1  1  1  0  0
  1  1  0  0  1  0  0  0

--> bitget(ns,1:8)
 ans  =
  0  0  1  1  0  0  0  0
  1  1  1  0  0  0  0  0
  1  1  1  1  0  1  0  0
  1  1  1  0  0  0  0  0
]]></screen>
        <para>
		Установка отдельного бита в каждом элементе массива по индексу бита в зависимости от элемента, поэлементно:
        </para>
        <programlisting role="example"><![CDATA[
n = uint16([94 78 ; 6 19])
ns = bitset(n, [2 4 ; 3 5], 0)            // в одно и то же значение бита 0
ns2 = bitset(n, [1 3 ; 2 4], [1 0 ; 0 1]) // в соответствующие значения битов
// Анализ:
bitget(ns, 1:8)  // #[2 3 4 5] устанавливаются в 0
bitget(n, 1:8)   // вход
bitget(ns2, 1:8) // #[1 2 3 4] устанавливаются в [1 0 0 1]
   ]]></programlisting>
   <screen><![CDATA[
--> n = uint16([94 78 ; 6 19])
 n  =
  94  78
   6  19

--> ns = bitset(n, [2 4 ; 3 5], 0)            // в одно и то же значение бита 0
 ns  =
  92  70
   2   3

--> ns2 = bitset(n, [1 3 ; 2 4], [1 0 ; 0 1]) // в соответствующие значения битов
 ns2  =
  95  74
   4  27

--> // Анализ:
--> bitget(ns, 1:8)    // #[2 3 4 5] устанавливаются в 0
 ans  =
  0  0  1  1  1  0  1  0
  0  1  0  0  0  0  0  0
  0  1  1  0  0  0  1  0
  1  1  0  0  0  0  0  0

--> bitget(n, 1:8)     // вход
 ans  =
  0  1  1  1  1  0  1  0
  0  1  1  0  0  0  0  0
  0  1  1  1  0  0  1  0
  1  1  0  0  1  0  0  0

--> bitget(ns2, 1:8)    // #[1 2 3 4] устанавливаются в [1 0 0 1]
 ans  =
  1  1  1  1  1  0  1  0
  0  0  1  0  0  0  0  0
  0  1  0  1  0  0  1  0
  1  1  0  1  1  0  0  0
]]></screen>
        <para>
           Установка нескольких битов в каждом входном элементе, поэлементно:
        </para>
        <programlisting role="example"><![CDATA[
// Биты устанавливаются в 1:
n = int64([6 49 71]);
bitInd = cat(3, [1 3 5], [2 4 6])
ns = bitset(n, bitInd)
bitget(n, 1:8)
bitget(ns, 1:8)
   ]]></programlisting>
   <screen><![CDATA[
--> n = int64([6 49 71]);
--> bitInd = cat(3, [1 3 5], [2 4 6])
 bitInd  =
(:,:,1)
   1.   3.   5.
(:,:,2)
   2.   4.   6.

--> ns = bitset(n, bitInd)
 ns  =
  7  61  119

--> bitget(n, 1:8)
 ans  =
  0  1  1  0  0  0  0  0
  1  0  0  0  1  1  0  0
  1  1  1  0  0  0  1  0

--> bitget(ns, 1:8)
 ans  =
  1  1  1  0  0  0  0  0
  1  0  1  1  1  1  0  0
  1  1  1  0  1  1  1  0
]]></screen>
        <para/>
        <programlisting role="example"><![CDATA[
// Биты устанавливаются в соответствующие значения:
n = uint64([6 49 71]);
bitInd = cat(3, [1 3 5], [2 4 6])
bitVal = cat(3, [1 1 1], [0 0 0])
n
ns = bitset(n, bitInd, bitVal)
bitget(n, 1:8)
bitget(ns, 1:8)
   ]]></programlisting>
   <screen><![CDATA[
--> bitInd = cat(3, [1 3 5], [2 4 6])
 bitInd  =
(:,:,1)
   1.   3.   5.
(:,:,2)
   2.   4.   6.

--> bitVal = cat(3, [1 1 1], [0 0 0])
 bitVal  =
(:,:,1)
   1.   1.   1.
(:,:,2)
   0.   0.   0.

--> n
 n  =
  6  49  71

--> ns = bitset(n, bitInd, bitVal)
 ns  =
  5  53  87

--> bitget(n, 1:8)
 ans  =
  0  1  1  0  0  0  0  0
  1  0  0  0  1  1  0  0
  1  1  1  0  0  0  1  0

--> bitget(ns, 1:8)
 ans  =
  1  0  1  0  0  0  0  0
  1  0  1  0  1  1  0  0
  1  1  1  0  1  0  1  0
]]></screen>
        <para>
           Установка битов в десятичных числах, даже для больших чисел:
        </para>
        <programlisting role="example"><![CDATA[
n = [0 1.2345e20];
showBits =     [1 10 40 50 60 61 62 63 64 65 66];
ns = bitset(n, [  10 40       61    63 64 65   ], ..
               [   1  0        1     1  0  1   ])
[bitget(n, showBits); showBits ; bitget(ns, showBits)] // [перед ; № бита ; после]
// биты в №<(65|66 - 53) являются неизвестными
   ]]></programlisting>
   <screen><![CDATA[
--> ns = bitset(n, [  10 40       61    63 64 65   ], ..
  >                [   1  0        1     1  0  1   ])
 ns  =
   2.421D+19   1.373D+20

--> [bitget(n, showBits); showBits ; bitget(ns, showBits)] // [перед ; № бита ; после]
 ans  =
   0.    0.    0.    0.    0.    0.    0.    0.    0.    0.    0.
   Nan   Nan   1.    1.    0.    1.    1.    0.    1.    0.    1.
   1.    10.   40.   50.   60.   61.   62.   63.   64.   65.   66.
   Nan   Nan   0.    0.    0.    1.    0.    1.    0.    1.    0.
   Nan   Nan   0.    1.    0.    1.    1.    1.    0.    1.    1.

--> // биты в №<(65|66 - 53) являются неизвестными
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="bitget">bitget</link>
            </member>
            <member>
                <link linkend="or_op">|, ||</link>
            </member>
            <member>
                <link linkend="and_op">&amp;, &amp;&amp;</link>
            </member>
            <member>
                <link linkend="or">or</link>
            </member>
            <member>
                <link linkend="and">and</link>
            </member>
            <member>
                <link linkend="bin2dec">bin2dec</link>
            </member>
            <member>
                <link linkend="dec2bin">dec2bin</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>История</title>
        <revhistory>
            <revision>
                <revnumber>5.0</revnumber>
                <revdescription>
                    Функция введена.
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            Теперь поддерживаются 64-битные целые числа.
                        </listitem>
                        <listitem>
                            Добавлена поддержка для положительных знаковых целых чисел.
                        </listitem>
                        <listitem>
                            Для десятичных чисел биты от №53 до №1024 теперь могут быть должным образом установлены.
                        </listitem>
                        <listitem>
                            Для каждого входного элемента теперь несколько битов могут быть установлены одновременно.
                        </listitem>
                        <listitem>
                          Входные аргументы теперь могут смешивать массивы и скаляры вместо обязательных
                          поэлементных массивов.
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
