---
name: bit32
last_updated: 2026-06-19T03:26:26Z
type: library
summary: "A library of functions to perform bitwise operations."
---

# bit32

A library of functions to perform bitwise operations.

**Type:** library

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

![32-bit integer conversion (in hexadecimal)](../../../assets/engine-api/libraries/bit32/32-Bit-Restriction.png)

## Functions

### bit32.arshift

**Signature:** `bit32.arshift(x: number, disp: number): 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:**

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

**Returns:** `number`

### bit32.band

**Signature:** `bit32.band(numbers: Tuple): number`

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 |

![Bitwise AND of 3 numbers](../../../assets/engine-api/libraries/bit32/AND.png)

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `numbers` | `Tuple` |  |  |

**Returns:** `number`

### bit32.bnot

**Signature:** `bit32.bnot(x: number): number`

Returns the bitwise negation of `x`.

![Negation of a provided number](../../../assets/engine-api/libraries/bit32/NOT.png)

For any integer `x`, the following identity holds:

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### bit32.bor

**Signature:** `bit32.bor(numbers: Tuple): number`

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 |

![Bitwise OR of 3 numbers](../../../assets/engine-api/libraries/bit32/OR.png)

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `numbers` | `Tuple` |  |  |

**Returns:** `number`

### bit32.btest

**Signature:** `bit32.btest(numbers: Tuple): bool`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `numbers` | `Tuple` |  |  |

**Returns:** `bool`

### bit32.bxor

**Signature:** `bit32.bxor(numbers: Tuple): number`

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 |

![Bitwise XOR of 3 numbers](../../../assets/engine-api/libraries/bit32/XOR.png)

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `numbers` | `Tuple` |  |  |

**Returns:** `number`

### bit32.byteswap

**Signature:** `bit32.byteswap(x: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### bit32.countlz

**Signature:** `bit32.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.
Returns 32 if the provided number is zero.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `n` | `number` |  |  |

**Returns:** `number`

### bit32.countrz

**Signature:** `bit32.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. Returns 32 if the provided number is zero.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `n` | `number` |  |  |

**Returns:** `number`

### bit32.extract

**Signature:** `bit32.extract(n: number, field: number, width?: number): 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:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `n` | `number` |  |  |
| `field` | `number` |  |  |
| `width` | `number` | `1` |  |

**Returns:** `number`

### bit32.replace

**Signature:** `bit32.replace(n: number, v: number, field: number, width?: number): number`

Returns a copy of `n` with the bits `field` to `field + width - 1`
replaced by the value `v`. See [bit32.extract()](/docs/reference/engine/globals/bit32.md) for details about
`field` and `width`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `n` | `number` |  |  |
| `v` | `number` |  |  |
| `field` | `number` |  |  |
| `width` | `number` | `1` |  |

**Returns:** `number`

### bit32.lrotate

**Signature:** `bit32.lrotate(x: number, disp: number): 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:

```lua
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` |  |  |
| `disp` | `number` |  |  |

**Returns:** `number`

### bit32.lshift

**Signature:** `bit32.lshift(x: number, disp: number): 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](../../../assets/engine-api/libraries/bit32/LSHIFT.png)

For positive displacements, the following equality holds:

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `disp` | `number` |  |  |

**Returns:** `number`

### bit32.rrotate

**Signature:** `bit32.rrotate(x: number, disp: number): 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:

```lua
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` |  |  |
| `disp` | `number` |  |  |

**Returns:** `number`

### bit32.rshift

**Signature:** `bit32.rshift(x: number, disp: number): 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](../../../assets/engine-api/libraries/bit32/RSHIFT.png)

For positive displacements, the following equality holds:

```lua
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` |  |  |
| `disp` | `number` |  |  |

**Returns:** `number`