bitset Sets bits of given indices in some integers

## Syntax

                y = bitset(x, bitInd)
                y = bitset(x, bitInd, bitVal)

## Parameters

x

  positive decimal or encoded integers (all inttypes supported), whose bits must be set. Supported sizes: scalar, vector, matrix, hypermatrix.

bitInd

  Indices of bits to be set: Array of positive decimal or encoded integers (all inttypes supported), whose values are in the interval `[1 bitmax]` where `bitmax` is the maximal index of bits for the type of `x`. The bit #1 is the lightest one (20).

  typeof(x) | bitmax | .. | typeof(x) | bitmax
  int8 | 7 |  | uint8 | 8
  int16 | 15 |  | uint16 | 16
  int32 | 31 |  | uint32 | 32
  int64 | 63 |  | uint16 | 64
  decimal | 1024 |  |  |

  - If the size of `bitInd` matches `x`'s one, the processing is performed element-wise: For every index i in x, the bit #bitInd(i) is set in x(i).

  - If `x` has N dimensions and the N first sizes of `bitInd` match `x` ones, and `bitInd` has N+1 dimensions, then for each `x(i1,i2,..iN)`, all its bits `#bitInd(i1,i2,..iN, :)` are set.

  - Otherwise: `bitInd` must be a vector of length<= `bitmax`. Then, all the bits listed in `bitInd` are set in all `x` components.

bitVal

  Array of values 0 or 1 as decimal or encoded integers (all inttypes supported) : values to which respective bits must be set. `bitVal` has either the size of `bitInd`, or it is scalar (then the same value is used for all bits).

y

  Processed `x`, with the same size and data type (and integer type) as `x`.

## Description

Sets the bits of `x` indicated by `bitInd`, either to 1 or to the given values `bitVal`.

## Examples

Setting one or several bits in a scalar:

    n = int8(20);
    ns = bitset(n, [1 3 6]) // setting bits #1 #3 #6 (to 1 by default)
    bitget([n ns], 1:7)     // bits content before / after setting

    ns = bitset(n, [1 3 6], [1 0 1]) // to explicit bits values
    bitget([n ns], 1:7)

    --> n = int8(20);
    --> ns = bitset(n, [1 3 6]) // setting bits #1 #3 #6 (to 1 by default)
     ns  =
      53

    --> bitget([n ns], 1:7)     // bits content before / after setting
     ans  =
      0  0  1  0  1  0  0
      1  0  1  0  1  1  0

    --> ns = bitset(n, [1 3 6], [1 0 1]) // to explicit bits values
     ns  =
      49

    --> bitget([n ns], 1:7)
     ans  =
      0  0  1  0  1  0  0
      1  0  0  0  1  1  0

Setting the same bits to the same respective values for all input elements:

    n = uint16([28  59; 23  19])
    ns = bitset(n, [3 5], [1 0])
    bitget(n, 1:8)
    bitget(ns,1:8)

    --> 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

Setting a single bit of each element of an array, at a bit index depending on the element, in an element-wise way:

    n = uint16([94 78 ; 6 19])
    ns = bitset(n, [2 4 ; 3 5], 0)            // To the same bit value 0
    ns2 = bitset(n, [1 3 ; 2 4], [1 0 ; 0 1]) // To respective bits values
    // Analysis:
    bitget(ns, 1:8)  // #[2 3 4 5] set to 0
    bitget(n, 1:8)   // input
    bitget(ns2, 1:8) // #[1 2 3 4] set to [1 0 0 1]

    --> n = uint16([94 78 ; 6 19])
     n  =
      94  78
       6  19

    --> ns = bitset(n, [2 4 ; 3 5], 0)            // To the same bit value 0
     ns  =
      92  70
       2   3

    --> ns2 = bitset(n, [1 3 ; 2 4], [1 0 ; 0 1]) // To respective bits values
     ns2  =
      95  74
       4  27

    --> // Analysis:
    --> bitget(ns, 1:8)    // #[2 3 4 5] set to 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)     // input
     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] set to [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

Setting several bits in each input element, in an element-wise way:

    // Bits set to 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)

    --> 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

    // Bits set to respective values:
    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)

    --> 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

Setting bits in decimal numbers, even for big numbers:

    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)] // [before ; bits # ; after]
    // bits at #<(65|66 - 53) are unknown

    --> 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)] // [before ; bits # ; after]
     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.

    --> // bits at #<(65|66 - 53) are unknown

## See Also

- bitget
- |, ||
- &, &&
- or
- and
- bin2dec
- dec2bin

## History

5.0 Function introduced
6.1.0

- 64-bit integers now supported.
- Support to positive signed integers added.
- With decimal numbers, bits #53 to #1024 can now be properly set.
- For each input element, several bits can now be set at the same time.
- Input arguments can now mixed arrays and scalars, instead of mandatory element-wise arrays.