bitcmp bitwise complement of integers

## Syntax

                y = bitcmp(x)
                y = bitcmp(x, bitnum)

## Arguments

x, y
  arrays of signed or unsigned integers (int8, .., uint64), or of positive decimal integers. Hypermatrix supported. `x` and `y` have the same integer type and the same size.

bitnum
  positive encoded or decimal integer, or array of positive encoded or decimal integers of size equal to size(x): bits #1 to #bitnum of `x` are considered and inversed. According to the integer type of `x`, `bitnum` must be in the interval `[1, bitmax]` with bitmax as follows:

  inttype : | int8 | uint8 | int16 | uint16 | int32 | uint32 | int64 | uint64 | decimal
  bitmax : | 8 | 8 | 16 | 16 | 32 | 32 | 64 | 64 | 1024

  The default `bitnum` value depends on the input integer type:
  - `bitnum = bitmax` for encoded integers
  - `bitnum = 53` for decimal integers `x ≤ 1/%eps`
  - `bitnum = int(log2(x))+1` for decimal integers `x > 1/%eps`.

## Description

`bitcmp(x)` computes the binary complement of each element of `x`, and provides it in the corresponding element of `y`.

In the following description, 2^0 corresponds to the bit #1. An integer whose highest bit on is #n, is in `[2^(n-1), 2^n-1]`.

For `x` such that `abs(x) ≥ 2^bitnum`, its bits `#(bitnum+1)` to `#(int(log2(x))+1)` are ignored. Only its bits `#1` to `#bitnum` are considered and inversed.

Example:

    --> bitget(180, 1:8)
     ans  =
       0.   0.   1.   0.   1.   1.   0.   1.
    --> bitcmp(180, 4)
     ans  =
       11.
    --> bitget(11, 1:8)
     ans  =
       1.   1.   0.   1.   0.   0.   0.   0.

For `x` such that `abs(x) < 2^bitnum`, bits `#(int(log2(x))+2)` to `#bitnum` are padded with 0. Then all bits `#1` to `#bitnum` are considered and inversed.

Example:

    --> x = 30; int(log2(30))+2
     ans  =
       6.
    --> bitget(30, 1:10)
     ans  =
       0.   1.   1.   1.   1.   0.   0.   0.   0.   0.
    --> bitcmp(30, 7)
     ans  =
       97.
    --> bitget(97, 1:10)
     ans  =
       1.   0.   0.   0.   0.   1.   1.   0.   0.   0.

## Examples

    x = uint8(13);
    b = bitget(x, 1:8)
    c = bitcmp(x, 8)
    bitget(c, 1:8)
    1 - b

    --> b = bitget(x, 1:8)
     b  =
      1  0  1  1  0  0  0  0

    --> c = bitcmp(x, 8)
     c  =
      242

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

    --> 1 - b
     ans  =
      0  1  0  0  1  1  1  1

Negative encoded integers are accepted:

    bitcmp(int8([-71 -34 -1 0 33 70]))
    bitcmp(int8([-71 -34 -1 0 33 70]), 8)
    bitcmp(int8([-71 -34 -1 0 33 70]), 7)
    bitcmp(int8([-71 -34 -1 0 33 70]), 6)
    bitcmp(int8([-71 -34 -1 0 33 70]), 5)
    bitcmp(int8([-71 -34 -1 0 33 70]), 4)

    --> bitcmp(int8([-71 -34 -1 0 33 70]))
     ans  =
      70  33  0 -1 -34 -71

    --> bitcmp(int8([-71 -34 -1 0 33 70]), 8)
     ans  =
      70  33  0 -1 -34 -71

    --> bitcmp(int8([-71 -34 -1 0 33 70]), 7)
     ans  =
      70  33  0  127  94  57

    --> bitcmp(int8([-71 -34 -1 0 33 70]), 6)
     ans  =
      6  33  0  63  30  57

    --> bitcmp(int8([-71 -34 -1 0 33 70]), 5)
     ans  =
      6  1  0  31  30  25

    --> bitcmp(int8([-71 -34 -1 0 33 70]), 4)
     ans  =
      6  1  0  15  14  9

We can work with 64-bit big integers:

    b = (rand(1,62)<0.5)*1;
    x = sum(b .* (uint64(2).^(0:61)))
    r = bitcmp(x)
    bg = bitget(r, 1:62);
    [msprintf("%d ",b(:)) ; msprintf("%d ",bg(:))]

    --> x = sum(b .* (uint64(2).^(0:61)))
     x  =
      4154509482123930814

    --> r = bitcmp(x)
     r  =
      14292234591585620801

    --> bg = bitget(r, 1:62);
    --> [msprintf("%d ",b(:)) ; msprintf("%d ",bg(:))]
     ans  =
      "0 1 1 1 1 1 0 1 0 0 1 1 0 1 0 0 ... 1 0 0 0 0 1 0 0 1 1 1 1 1 0 0 1 0 1 1 0 0 1 1 1 "
      "1 0 0 0 0 0 1 0 1 1 0 0 1 0 1 1 ... 0 1 1 1 1 0 1 1 0 0 0 0 0 1 1 0 1 0 0 1 1 0 0 0 "

bitnum can be an array:

    bitcmp([0 0 0 0 0], 3:7)

    --> bitcmp([0 0 0 0 0], 3:7)
     ans  =
       7.   15.   31.   63.   127.

bitnum can be > 52:

    format(22)
    bitcmp(2^70, 65)
    sum(2.^(13:64))   // 52 highest bits

    --> bitcmp(2^70, 65)
     ans  =
       36893488147419095040.

    --> sum(2.^(13:64))
     ans  =
       36893488147419095040.

Huge decimal numbers can be processed:

    format(22)
    log2(1e100)
    r = bitcmp(1e100, 333)
    bitcmp(1e100) // bitnum = int(log2(x)) + 1 is used by default
    bitcmp(r, 333)

    --> log2(1e100)
     ans  =
       332.19280948873625903

    --> r = bitcmp(1e100, 333)
     r  =
       7.498005798264093D+99

    --> bitcmp(1e100)  // bitnum = int(log2(x)) + 1 is used by default
     ans  =
       7.498005798264093D+99

    --> bitcmp(r, 333)
     ans  =
       1.00000000000000D+100

## See Also

- bitxor
- bitget
- minus

## History

6.1.1

- Extension to 64 bit integers.
- Extension to all signed integers.
- Decimal positive integers > 2^52 up to 2^1024 = number_properties("huge") can now be processed, with bitnum up to 1024 instead of 52.
- bitnum is now optional as well for input decimal integers. It can actually be an array.