Lua Bit Operations Guide — Bit32 Library and Bit Manipulation

In this tutorial, you will learn about Lua Bit Operations Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Lua bit32 library (Lua 5.2+) provides bitwise operations on 32-bit integers including AND, OR, XOR, NOT, left shift, right shift, and rotation -- essential for flags manipulation, network protocols, and low-level hardware interaction.

Basic Bit Operations

local b = bit32

-- AND: bits set in both
print(b.band(0b1100, 0b1010))  --> 8 (0b1000)

-- OR: bits set in either
print(b.bor(0b1100, 0b1010))   --> 14 (0b1110)

-- XOR: bits set in exactly one
print(b.bxor(0b1100, 0b1010))  --> 6 (0b0110)

-- NOT: invert all bits
print(b.bnot(0b00001111))      --> 0xFFFFFFF0

Shifts and Rotations

local b = bit32

-- Left shift
print(b.lshift(0b0001, 3))     --> 8 (0b1000)

-- Right shift (logical)
print(b.rshift(0b1000, 3))     --> 1 (0b0001)

-- Right shift (arithmetic, preserves sign)
print(b.arshift(-8, 3))        --> -1

-- Left rotation
print(b.lrotate(0x80000001, 1))  --> 0x00000003

-- Right rotation
print(b.rrotate(0x00000003, 1))  --> 0x80000001

Flag Manipulation

local READ = 0b001
local WRITE = 0b010
local EXECUTE = 0b100

-- Set permissions
local permissions = 0
permissions = b.bor(permissions, READ)
permissions = b.bor(permissions, EXECUTE)

-- Check permissions
if b.band(permissions, READ) ~= 0 then
    print("Read permission granted")
end

-- Remove permission
permissions = b.band(permissions, b.bnot(EXECUTE))

Packing and Unpacking

-- Pack bytes into word
local r, g, b = 255, 128, 64
local pixel = b.bor(
    b.lshift(r, 16),
    b.lshift(g, 8),
    b
)
print(string.format("0x%06X", pixel))  --> 0xFF8040

-- Unpack word into bytes
local r = b.band(b.rshift(pixel, 16), 0xFF)
local g = b.band(b.rshift(pixel, 8), 0xFF)
local b = b.band(pixel, 0xFF)

Common Mistakes

1. Assuming 64-bit operations

bit32 only works on 32 bits. For 64-bit, use Lua 5.3+ integers with &, |, ~ operators.

2. Confusing logical and arithmetic right shift

rshift fills with zeros (logical). arshift fills with sign bit (preserves sign for signed numbers).

3. Forgetting to mask after shift

A right shift of 40 on a 32-bit value still produces defined results -- bit32 masks shift amounts by 31.

Practice Questions

1. How do you set a specific bit? Use OR: value = b.bor(value, bitmask) where bitmask has the target bit set to 1.

2. How do you clear a specific bit? Use AND with inverted mask: value = b.band(value, b.bnot(bitmask)).

3. How do you toggle a bit? Use XOR: value = b.bxor(value, bitmask).

FAQ

{{< faq question="Is bit32 available in all Lua versions?" >}} bit32 was introduced in Lua 5.2. Lua 5.3+ has built-in bitwise operators (&, |, ~, <<, >>). Lua 5.1 requires a library. {{< /faq >}}

{{< faq question="What is the difference between rshift and arshift?" >}} rshift (logical) fills with zeros. arshift (arithmetic) fills with the sign bit, preserving the sign of negative numbers. {{< /faq >}}

{{< faq question="Can I do bitwise operations on numbers larger than 32 bits?" >}} In Lua 5.3+, use the built-in operators &, |, etc. which work on 64-bit integers. bit32 is limited to 32 bits. {{< /faq >}}

What's Next

Now learn about data persistence in Lua.