4.5 Bit Manipulations

Octave provides a number of functions for the manipulation of numeric values on a bit by bit basis. The basic functions to set and obtain the values of individual bits are bitset and bitget.

: C = bitset (A, n) ¶

: C = bitset (A, n, val) ¶

Set or reset bit(s) n of the unsigned integers in A.

The least significant bit is n = 1. val = 0 resets bits and val = 1 sets bits. If no val is specified it defaults to 1 (set bit). All inputs must be the same size or scalars.

Example 1: Set multiple bits

x = bitset (1, 3:5)
  ⇒ x =

   5    9   17

dec2bin (x)
  ⇒
     00101
     01001
     10001

Example 2: Reset and set bits

x = bitset ([15 14], 1, [0 1])
  ⇒ x =

   14    15

See also: bitand, bitor, bitxor, bitget, bitcmp, bitshift, intmax, flintmax.

: c = bitget (A, n) ¶

Return the status of bit(s) n of the unsigned integers in A.

The least significant bit is n = 1.

bitget (100, 8:-1:1)
⇒ 0  1  1  0  0  1  0  0

See also: bitand, bitor, bitxor, bitset, bitcmp, bitshift, intmax, flintmax.

The arguments to all of Octave’s bitwise operations can be scalar or arrays, except for bitcmp, whose k argument must a scalar. In the case where more than one argument is an array, then all arguments must have the same shape, and the bitwise operator is applied to each of the elements of the argument individually. If at least one argument is a scalar and one an array, then the scalar argument is duplicated. Therefore

bitget (100, 8:-1:1)

is the same as

bitget (100 * ones (1, 8), 8:-1:1)

It should be noted that all values passed to the bit manipulation functions of Octave are treated as integers. Therefore, even though the example for bitset above passes the floating point value 10, it is treated as the bits [1, 0, 1, 0] rather than the bits of the native floating point format representation of 10.

As the maximum value that can be represented by a number is important for bit manipulation, particularly when forming masks, Octave supplies two utility functions: flintmax for floating point integers, and intmax for integer objects (uint8, int64, etc.).

Octave also includes the basic bitwise ’and’, ’or’, and ’exclusive or’ operators.

: bitand (x, y) ¶

Return the bitwise AND of non-negative integers.

x, y must be in the range [0,intmax]

See also: bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax.

: bitor (x, y) ¶

Return the bitwise OR of non-negative integers x and y.

See also: bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax.

: bitxor (x, y) ¶

Return the bitwise XOR of non-negative integers x and y.

See also: bitand, bitor, bitset, bitget, bitcmp, bitshift, intmax, flintmax.

The bitwise ’not’ operator is a unary operator that performs a logical negation of each of the bits of the value. For this to make sense, the mask against which the value is negated must be defined. Octave’s bitwise ’not’ operator is bitcmp.

: bitcmp (A, k) ¶

Return the k-bit complement of integers in A.

If k is omitted k = log2 (flintmax) + 1 is assumed.

bitcmp (7,4)
  ⇒ 8
dec2bin (11)
  ⇒ 1011
dec2bin (bitcmp (11, 6))
  ⇒ 110100

See also: bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, flintmax.

Octave also includes the ability to left-shift and right-shift values bitwise.

: bitshift (a, k) ¶

: bitshift (a, k, n) ¶

Return a k bit shift of n-digit unsigned integers in a.

A positive k leads to a left shift; A negative value to a right shift.

If n is omitted it defaults to 64. n must be in the range [1,64].

bitshift (eye (3), 1)
⇒

2 0 0
0 2 0
0 0 2

bitshift (10, [-2, -1, 0, 1, 2])
⇒ 2   5  10  20  40

See also: bitand, bitor, bitxor, bitset, bitget, bitcmp, intmax, flintmax.

Bits that are shifted out of either end of the value are lost. Octave also uses arithmetic shifts, where the sign bit of the value is kept during a right shift. For example:

bitshift (-10, -1)
⇒ -5
bitshift (int8 (-1), -1)
⇒ -1

Note that bitshift (int8 (-1), -1) is -1 since the bit representation of -1 in the int8 data type is [1, 1, 1, 1, 1, 1, 1, 1].