9 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

bit32

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)

Functions

Name	Type / Returns	Description
bit32.arshift	number	Returns a number after its bits have been arithmetically shifted to the right by a given displacement.
bit32.band	number	Returns the bitwise AND of all provided numbers.
bit32.bnot	number	Returns the bitwise negation of a given number.
bit32.bor	number	Returns the bitwise OR of all provided numbers.
bit32.btest	bool	Returns a boolean describing whether the bitwise and of its operands is different from zero.
bit32.bxor	number	Returns the bitwise XOR of all provided numbers.
bit32.byteswap	number	Returns the given number with the order of the bytes swapped.
bit32.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.
bit32.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.
bit32.extract	number	Extract a range of bits from a number and return them as an unsigned number.
bit32.replace	number	Return a copy of a number with a range of bits replaced by a given value.
bit32.lrotate	number	Returns a number after its bits have been rotated to the left by a given number of times.
bit32.lshift	number	Returns a number whose bits have been logically shifted to the left by a given displacement.
bit32.rrotate	number	Returns a number after its bits have been rotated to the right by a given number of times.
bit32.rshift	number	Returns a number whose bits have been logically shifted to the right by a given displacement.

bit32.arshift

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

Name	Type	Default	Description
x	number		The number whose bits shall be shifted.
disp	number		The integer number of bits to shift by.

Returns

Type	Description
number	The result of arithmetically shifting `x` by `disp` bits to the right.

bit32.band

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

Parameters

Name	Type	Default	Description
numbers	Tuple		The numbers to combine with bitwise AND.

Returns

Type	Description
number	The bitwise AND of all provided numbers.

bit32.bnot

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)

Parameters

Name	Type	Default	Description
x	number		The number to negate.

Returns

Type	Description
number	The bitwise negation of `x`.

bit32.bor

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

Parameters

Name	Type	Default	Description
numbers	Tuple		The numbers to combine with bitwise OR.

Returns

Type	Description
number	The bitwise OR of all provided numbers.

bit32.btest

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)

Parameters

Name	Type	Default	Description
numbers	Tuple		The numbers to test with bitwise AND.

Returns

Type	Description
bool	True if the bitwise AND of all operands is non-zero, false otherwise.

bit32.bxor

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

Parameters

Name	Type	Default	Description
numbers	Tuple		The numbers to combine with bitwise XOR.

Returns

Type	Description
number	The bitwise XOR of all provided numbers.

bit32.byteswap

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.

Parameters

Name	Type	Default	Description
x	number		The number whose bytes to swap.

Returns

Type	Description
number	The number with its byte order reversed.

bit32.countlz

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

Name	Type	Default	Description
n	number		The number to count leading zeros in.

Returns

Type	Description
number	The count of consecutive zero bits from the most significant bit, or 32 if `n` is zero.

bit32.countrz

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

Name	Type	Default	Description
n	number		The number to count trailing zeros in.

Returns

Type	Description
number	The count of consecutive zero bits from the least significant bit, or 32 if `n` is zero.

bit32.extract

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

Name	Type	Default	Description
n	number		The number to extract bits from.
field	number		The zero-based position of the least significant bit to extract.
width	number	1	The number of bits to extract.

Returns

Type	Description
number	The unsigned number formed by the extracted bit range.

bit32.replace

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

Name	Type	Default	Description
n	number		The number in which to replace bits.
v	number		The replacement value to insert into the bit range.
field	number		The zero-based position of the least significant bit to replace.
width	number	1	The number of bits to replace.

Returns

Type	Description
number	A copy of `n` with the specified bit range replaced by `v`.

bit32.lrotate

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.

Parameters

Name	Type	Default	Description
x	number		The number whose bits to rotate.
disp	number		The number of bit positions to rotate left.

Returns

Type	Description
number	The result of rotating `x` left by `disp` bits.

bit32.lshift

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)

Parameters

Name	Type	Default	Description
x	number		The number whose bits to shift.
disp	number		The number of bit positions to shift left.

Returns

Type	Description
number	The result of logically shifting `x` left by `disp` bits.

bit32.rrotate

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.

Parameters

Name	Type	Default	Description
x	number		The number whose bits to rotate.
disp	number		The number of bit positions to rotate right.

Returns

Type	Description
number	The result of rotating `x` right by `disp` bits.

bit32.rshift

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.

Parameters

Name	Type	Default	Description
x	number		The number whose bits to shift.
disp	number		The number of bit positions to shift right.

Returns

Type	Description
number	The result of logically shifting `x` right by `disp` bits.