bit32

Show Deprecated

This library provides functions to perform bitwise operations.

Number Limitations

This library treats numbers as unsigned 32-bit integers; numbers will be converted to this before being used (see image below). Numbers with decimal numbers are rounded to the nearest whole number.

32-bit integer conversion (in hexadecimal)

Summary

Functions

  • arshift(x : number,disp : number):number

    Returns a number after its bits have been arithmetically shifted to the right by a given displacement.

  • band(numbers : Tuple):number

    Returns the bitwise AND of all provided numbers.

  • bnot(x : number):number

    Returns the bitwise negation of a given number.

  • bor(numbers : Tuple):number

    Returns the bitwise OR of all provided numbers.

  • btest(numbers : Tuple):bool

    Returns a boolean describing whether the bitwise and of its operands is different from zero.

  • bxor(numbers : Tuple):number

    Returns the bitwise XOR of all provided numbers.

  • byteswap(x : number):number

    Returns the given number with the order of the bytes swapped.

  • countlz(n : number):number

    Returns the number of consecutive zero bits in the 32-bit representation of the provided number starting from the left-most (most significant) bit.

  • countrz(n : number):number

    Returns the number of consecutive zero bits in the 32-bit representation of the provided number starting from the right-most (least significant) bit.

  • extract(n : number,field : number,width : number):number

    Extract a range of bits from a number and return them as an unsigned number.

  • replace(n : number,v : number,field : number,width : number):number

    Return a copy of a number with a range of bits replaced by a given value.

  • lrotate(x : number,disp : number):number

    Returns a number after its bits have been rotated to the left by a given number of times.

  • lshift(x : number,disp : number):number

    Returns a number whose bits have been logically shifted to the left by a given displacement.

  • rrotate(x : number,disp : number):number

    Returns a number after its bits have been rotated to the right by a given number of times.

  • rshift(x : number,disp : number):number

    Returns a number whose bits have been logically shifted to the right by a given displacement.

Functions

arshift

number

Returns the number x shifted disp bits to the right. The number disp may be any representable integer. Negative displacements shift to the left.

This shift operation is what is called arithmetic shift. Vacant bits on the left are filled with copies of the higher bit of x; vacant bits on the right are filled with zeros. In particular, displacements with absolute values higher than 31 result in zero or 0xFFFFFFFF (all original bits are shifted out).

Parameters

x: number

The number whose bits shall be shifted.

disp: number

The integer number of bits to shift by.

Returns

number

band

number

Returns the bitwise AND of all provided numbers.

Each bit is tested against the following truth table:

ABOutput
000
100
010
111
Bitwise AND of 3 numbers

Parameters

numbers: Tuple

Returns

number

bnot

number

Returns the bitwise negation of x.

Negation of a provided number

For any integer x, the following identity holds:

assert(bit32.bnot(x) == (-1 - x) % 2^32)

Parameters

x: number

Returns

number

bor

number

Returns the bitwise OR of all provided numbers.

Each bit is tested against the following truth table:

ABOutput
000
101
011
111
Bitwise OR of 3 numbers

Parameters

numbers: Tuple

Returns

number

btest

bool

Returns a boolean signalling whether the bitwise and of its operands is different from zero.

Parameters

numbers: Tuple

Returns

bool

bxor

number

Returns the bitwise XOR of all provided numbers.

Each bit is tested against the following truth table:

ABOutput
000
101
011
110
Bitwise XOR of 3 numbers

Parameters

numbers: Tuple

Returns

number

byteswap

number

Returns the given number with the order of the bytes swapped.

Parameters

x: number

Returns

number

countlz

number

Returns the number of consecutive zero bits in the 32-bit representation of the provided number starting from the left-most (most significant) bit. Returns 32 if the provided number is zero.

Parameters

n: number

Returns

number

countrz

number

Returns the number of consecutive zero bits in the 32-bit representation of the provided number starting from the right-most (least significant) bit. Returns 32 if the provided number is zero.

Parameters

n: number

Returns

number

extract

number

Returns the unsigned number formed by the bits field to field + width - 1 from n. Bits are numbered from 0 (least significant) to 31 (most significant). All accessed bits must be in the range [0, 31]. The default for width is 1.

Parameters

n: number
field: number
width: number
Default Value: 1

Returns

number

replace

number

Returns a copy of n with the bits field to field + width - 1 replaced by the value v. See bit32.extract() for details about field and width.

Parameters

n: number
v: number
field: number
width: number
Default Value: 1

Returns

number

lrotate

number

Returns the number x rotated disp bits to the left. The number disp may be any representable integer. For any valid displacement, the following identity holds:

assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))

In particular, negative displacements rotate to the right.

Parameters

x: number
disp: number

Returns

number

lshift

number

Returns the number x shifted disp bits to the left. The number disp may be any representable integer. Negative displacements shift to the right. In any direction, vacant bits are filled with zeros. In particular, displacements with absolute values higher than 31 result in zero (all bits are shifted out).

Number shifted 3 to the left

For positive displacements, the following equality holds:

assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)

Parameters

x: number
disp: number

Returns

number

rrotate

number

Returns the number x rotated disp bits to the right. The number disp may be any representable integer.

For any valid displacement, the following identity holds:

assert(bit32.rrotate(x, disp) == bit32.rrotate(x , disp % 32))

In particular, negative displacements rotate to the left.

Parameters

x: number
disp: number

Returns

number

rshift

number

Returns the number x shifted disp bits to the right. The number disp may be any representable integer. Negative displacements shift to the left. In any direction, vacant bits are filled with zeros. In particular, displacements with absolute values higher than 31 result in zero (all bits are shifted out).

Number shifted 3 to the right

For positive displacements, the following equality holds:

assert(bit32.rshift(b, disp) == (b % 2^32 / 2^disp) // 1)

This shift operation is what is called logical shift.

Parameters

x: number
disp: number

Returns

number