bit32

Supported Library

A library of functions to perform bitwise operations.

Description

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.

Functions

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

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

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

band Supported Returns the bitwise AND of all provided numbers.

Returns the bitwise AND of all provided numbers.

Each bit is tested against the following truth table:

A	B	Output
0	0	0
1	0	0
0	1	0
1	1	1

bnot Supported Returns the bitwise negation of a given number.

Returns the bitwise negation of a given number.

Returns the bitwise negation of x.

For any integer x, the following identity holds:

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

bor Supported Returns the bitwise OR of all provided numbers.

Returns the bitwise OR of all provided numbers.

Each bit is tested against the following truth table:

A	B	Output
0	0	0
1	0	1
0	1	1
1	1	1

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

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

Returns true if the bitwise AND of all its operands is different from zero, false otherwise. This is functionally equivalent to bit32.band(...) ~= 0 but returns a boolean directly without the intermediate number.

This function is useful for testing whether one or more specific bits are set in a value. For example, you can check whether a particular flag is active in a bitmask:

local flags = 0x5 -- bits 0 and 2 are set
print(bit32.btest(flags, 1)) --> true (bit 0 is set)
print(bit32.btest(flags, 2)) --> false (bit 1 is not set)
print(bit32.btest(flags, 4)) --> true (bit 2 is set)

When called with more than two arguments, all values are ANDed together before the zero-test:

print(bit32.btest(0xFF, 0x0F, 0x03)) --> true (0xFF & 0x0F & 0x03 == 0x03)

bxor Supported Returns the bitwise XOR of all provided numbers.

Returns the bitwise XOR of all provided numbers.

Each bit is tested against the following truth table:

A	B	Output
0	0	0
1	0	1
0	1	1
1	1	0

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

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

Reverses the byte order of the 32-bit unsigned integer representation of x. The four bytes are rearranged so that the most-significant byte becomes the least-significant byte and vice versa, converting between big-endian and little-endian representations.

print(bit32.byteswap(0xAABBCCDD)) --> 0xDDCCBBAA
print(bit32.byteswap(0x00000001)) --> 0x01000000

This is useful when reading or writing binary data that uses a different byte order (endianness) than expected, such as network protocols or file formats that store multi-byte integers in big-endian order.

countlz Supported Returns the number of consecutive zero bits in the 32-bit representation of the provided number starting from the left-…

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.

countrz Supported Returns the number of consecutive zero bits in the 32-bit representation of the provided number starting from the right…

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.

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

Extract a range of bits from a number and return them as an unsigned 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). The default for width is 1.

For any valid field and width, this operation is equivalent to bit32.band(bit32.rshift(n, field), 2^width - 1). field must be in the range [0, 31], and width must be in the range [1, 32 - field]. Values outside those ranges raise an error.

local n = 0x12345678
assert(bit32.extract(n, 0, 8) == 0x78) -- bits 0 through 7
assert(bit32.extract(n, 4, 8) == 0x67) -- bits 4 through 11
assert(bit32.extract(n, 16, 8) == 0x34) -- bits 16 through 23
assert(bit32.extract(n, 24, 8) == 0x12) -- bits 24 through 31

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

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

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.

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

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

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:

local x, disp = 0xF0, 35
assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))

In particular, negative displacements rotate to the right.

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

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

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

For positive displacements, the following equality holds:

local b, disp = 0xF0, 3
assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)

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

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

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:

local x, disp = 0xF0, 35
assert(bit32.rrotate(x, disp) == bit32.rrotate(x , disp % 32))

In particular, negative displacements rotate to the left.

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

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

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

For positive displacements, the following equality holds:

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

This shift operation is what is called logical shift.

Roblox reference: bit32