bitget Extracts from integers bits of given indices

## Syntax

                y = bitget(x, pos)

## Parameters

x
  Scalar, vector, matrix or hypermatrix of positive decimal or encoded integers.

pos
  Scalar, vector, matrix or hypermatrix of decimal or encoded integers in `[1, bitmax]` where `bitmax` is the maximal index of bits for the type of `x`: Indices of bits to be extracted. 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 |  | uint64 | 64
  decimal | 1024 |  |  |

y

  Scalar, vector, matrix or hypermatrix of 0 and 1 of the type of `x`. The sizes and contents of `y` are as follows:

  If `x` is a scalar:

  - `y` has the sizes of `pos`
  - `y(i,j,..)` is the value of bit #`pos(i,j,..)` of `x`.

  If `pos` is a scalar:

  - `y` has the sizes of `x`
  - `y(i,j,..)` is the value of the bit #`pos` of `x(i,j,..)`.

  If `x` and `pos` are arrays with identical sizes, the processing is element-wise:

  - `y` has the sizes of `x` and `pos`
  - `y(i,j,..)` is the value of the bit #`pos(i,j,..)` of `x(i,j,..)`.

  Otherwise:

  - `y` is a matrix with `length(x)` rows and `length(pos)` columns.
  - `y(i,j)` is the value of the bit #`pos(j)` of `x(i)`.

## Description

`bitget()` scans chosen bits of the binary representation of some positive integers `x`. It returns 0 for bits down, and 1 for bits up.

The result has the sizes of `x` or of `pos` or of both inputs.

However, when both `x` and `pos` are non-scalar and have mismatching sizes, the result `y` is a matrix ignoring the sizes of `x`. Then, after reshaping `y` with `y = matrix(y, [size(x) -1])`, the value of the bit #b of `x(i,..,k)` is in `y(i,..,k,b)`.

## Examples

    // 19 is (10011)_2
    // The 2nd bit is 1 (starting from the end).
    x = uint8(19);
    pos = 2;
    y = bitget(x,pos)
    expected = 1;

    // 13 is (1101)_2
    dec2bin(13)
    bitget(uint8(13),4:-1:1)

With encoded integers:

    b = [1 3 8 11 15];
    x = sum(int16(2).^(b-1))
    B = bitget(x, 1:15)
    find(B)
    typeof(B)

    --> b = [1 3 8 11 15];
    --> x = sum(int16(2).^(b-1))
     x  =
      17541

    --> B = bitget(x, 1:15)
     B  =
      1  0  1  0  0  0  0  1  0  0  1  0  0  0  1

    --> find(B)
     ans  =
       1.   3.   8.   11.   15.

    --> typeof(B)
     ans  =
      "int16"

With uint64 integers > 252 :

    b = [1 12 23 34 45 53 64];
    x = sum(uint64(2).^(b-1))
    B = bitget(x, 1:64)
    find(B)
    typeof(B)

    --> b = [1 12 23 34 45 53 64];
    --> x = sum(uint64(2).^(b-1))
     x  =
      9227893237262321665

    --> B = bitget(x, 1:64)
     B  =
             column 1 to 32
     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

             column 33 to 64
     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

    --> find(B)
     ans  =
       1.   12.   23.   34.   45.   53.   64.

    --> typeof(B)
     ans  =
      "uint64"

With big decimal integers > 252 :

    x = sum(2 .^([7 16 18 19 25 52 70]-1))
    bitget(x,    [7 16 18 19 35 52 70 80])

    --> x = sum(2 .^([7 16 18 19 25 52 70]-1))
     x  =
       5.903D+20

    --> bitget(x,    [7 16 18 19 35 52 70 80])
     ans  =
       Nan   Nan   1.   1.   0.   1.   1.   0.

x and pos are arrays with mismatching sizes:

    x = [ 39  6   62
          8   14  29
          4   64  12
          44  39  50
          52  12  39
          5   4   29 ];
    x = sum(2.^(x-1),2);
    bitget(x, [5 8 12 39])

    --> bitget(x, [5 8 12 39])
     ans  =
       Nan   Nan   0.   1.
       0.    1.    0.   0.
       Nan   Nan   1.   0.
       0.    0.    0.   1.
       0.    0.    1.   1.
       1.    0.    0.   0.

## See Also

- bitstring
- dec2bin
- bitset
- bitand
- &

## History

6.1

- Positive signed integers are now accepted.
- 64 bits encoded integers are now accepted.
- For decimal integers, bits with index in [53, 1024] can now be retrieved.
- For decimal integers > 252, querying bits below the `%eps` relative accuracy now returns `NaN` instead of 0.
- It is now possible to retrieve several bits from each component of an input array.