Tables in Lua

Beginner ~30 min read

Tables are Lua's only data structuring mechanism, but don't let that fool you—they're incredibly versatile! Tables can be used as arrays, dictionaries, sets, objects, modules, and more. Understanding tables is essential to mastering Lua. In this lesson, you'll learn everything about creating, accessing, and manipulating tables. Let's dive in!

Creating Tables

Tables are created using curly braces {}:

-- Empty table
local empty = {}

-- Table with values
local numbers = {10, 20, 30, 40, 50}

-- Table with key-value pairs
local person = {
    name = "Alice",
    age = 25,
    city = "New York"
}

Important: Lua tables use 1-based indexing for arrays, not 0-based like most languages. The first element is at index 1!

-- Table Basics in Lua

-- Tables are Lua's only data structure!
-- They can be used as arrays, dictionaries, objects, and more

-- Empty table
local empty = {}
print("Empty table:", empty)

-- Array (sequential table) - 1-based indexing!
local fruits = {"apple", "banana", "cherry"}
print("\n=== Array ===")
print("First fruit:", fruits[1])  -- NOT fruits[0]!
print("Second fruit:", fruits[2])
print("Third fruit:", fruits[3])

-- Length operator
print("Number of fruits:", #fruits)

-- Adding to array
fruits[4] = "date"
print("After adding:", #fruits)

-- Dictionary (associative array)
local person = {
    name = "Alice",
    age = 25,
    city = "New York"
}

print("\n=== Dictionary ===")
print("Name:", person.name)
print("Age:", person["age"])  -- Both syntaxes work
print("City:", person.city)

-- Adding new key
person.email = "alice@example.com"
print("Email:", person.email)

-- Mixed table (both numeric and string keys)
local mixed = {
    "first",     -- index 1
    "second",    -- index 2
    name = "Mixed Table",
    count = 42
}

print("\n=== Mixed Table ===")
print("Index 1:", mixed[1])
print("Index 2:", mixed[2])
print("Name:", mixed.name)
print("Count:", mixed.count)

-- Nested tables
local company = {
    name = "TechCorp",
    employees = {
        {name = "Alice", role = "Developer"},
        {name = "Bob", role = "Designer"},
        {name = "Charlie", role = "Manager"}
    }
}

print("\n=== Nested Tables ===")
print("Company:", company.name)
print("First employee:", company.employees[1].name)
print("Their role:", company.employees[1].role)

-- Tables are passed by reference
local t1 = {1, 2, 3}
local t2 = t1  -- Same table, not a copy!

t2[1] = 100
print("\n=== Reference ===")
print("t1[1]:", t1[1])  -- 100 (changed!)
print("t2[1]:", t2[1])  -- 100

-- Copying a table (shallow copy)
local function copyTable(original)
    local copy = {}
    for k, v in pairs(original) do
        copy[k] = v
    end
    return copy
end

local original = {1, 2, 3}
local copy = copyTable(original)
copy[1] = 999

print("\n=== Copy ===")
print("Original[1]:", original[1])  -- 1 (unchanged)
print("Copy[1]:", copy[1])          -- 999

-- Checking if key exists
local data = {x = 10, y = 20}

if data.x then
    print("\nx exists:", data.x)
end

if data.z == nil then
    print("z does not exist")
end

Output

Click Run to execute your code

Tables as Arrays

Use tables with numeric indices as arrays:

local fruits = {"apple", "banana", "cherry"}

-- Access elements (1-based!)
print(fruits[1])  -- apple
print(fruits[2])  -- banana
print(fruits[3])  -- cherry

-- Get length
print(#fruits)  -- 3

-- Modify elements
fruits[2] = "blueberry"
print(fruits[2])  -- blueberry

-- Add elements
fruits[4] = "date"
table.insert(fruits, "elderberry")  -- Append to end

Warning: Arrays must have consecutive indices starting from 1. Gaps in indices can cause # to return unexpected results!

-- Arrays in Lua (Sequential Tables)

-- Creating arrays - 1-based indexing!
local numbers = {10, 20, 30, 40, 50}

print("=== Basic Array ===")
print("First element:", numbers[1])   -- 10
print("Last element:", numbers[5])    -- 50
print("Length:", #numbers)            -- 5

-- Iterating with ipairs (for arrays)
print("\n=== Iteration with ipairs ===")
for index, value in ipairs(numbers) do
    print(index, value)
end

-- Iterating with numeric for
print("\n=== Numeric for loop ===")
for i = 1, #numbers do
    print(i, numbers[i])
end

-- Multi-dimensional arrays
local matrix = {
    {1, 2, 3},
    {4, 5, 6},
    {7, 8, 9}
}

print("\n=== 2D Array ===")
for i = 1, #matrix do
    for j = 1, #matrix[i] do
        io.write(matrix[i][j] .. " ")
    end
    print()
end

-- Array of tables
local students = {
    {name = "Alice", grade = 95},
    {name = "Bob", grade = 87},
    {name = "Charlie", grade = 92}
}

print("\n=== Array of Tables ===")
for i, student in ipairs(students) do
    print(i .. ".", student.name, "-", student.grade)
end

-- Sparse arrays (gaps in indices)
local sparse = {}
sparse[1] = "first"
sparse[3] = "third"
sparse[5] = "fifth"

print("\n=== Sparse Array ===")
print("Length:", #sparse)  -- Undefined! Could be 1, 3, or 5

-- Use pairs for sparse arrays
for index, value in pairs(sparse) do
    print(index, value)
end

-- Array initialization patterns
local zeros = {}
for i = 1, 5 do
    zeros[i] = 0
end
print("\n=== Initialized Array ===")
print("Zeros:", table.concat(zeros, ", "))

-- Array with mixed types
local mixed = {42, "hello", true, {x = 10}, function() return "hi" end}

print("\n=== Mixed Types ===")
print("Number:", mixed[1])
print("String:", mixed[2])
print("Boolean:", mixed[3])
print("Table:", mixed[4].x)
print("Function:", mixed[5]())

-- Common array operations
local arr = {1, 2, 3, 4, 5}

-- Sum
local sum = 0
for i, v in ipairs(arr) do
    sum = sum + v
end
print("\n=== Operations ===")
print("Sum:", sum)

-- Find maximum
local max = arr[1]
for i = 2, #arr do
    if arr[i] > max then
        max = arr[i]
    end
end
print("Max:", max)

-- Reverse
local reversed = {}
for i = #arr, 1, -1 do
    table.insert(reversed, arr[i])
end
print("Reversed:", table.concat(reversed, ", "))

Output

Click Run to execute your code

Tables as Dictionaries

Use tables with string keys as dictionaries (hash maps):

local person = {
    name = "Alice",
    age = 25,
    city = "New York"
}

-- Access with dot notation
print(person.name)  -- Alice
print(person.age)   -- 25

-- Access with bracket notation
print(person["city"])  -- New York

-- Add new fields
person.email = "[email protected]"
person["phone"] = "555-1234"

-- Modify fields
person.age = 26

Dot vs Bracket Notation

Notation	Use When	Example
Dot	Key is a valid identifier	`person.name`
Bracket	Key has spaces, special chars, or is dynamic	`person["first name"]`

-- Dictionaries in Lua (Associative Arrays)

-- Creating a dictionary
local person = {
    name = "Alice",
    age = 25,
    city = "New York",
    email = "alice@example.com"
}

print("=== Basic Dictionary ===")
print("Name:", person.name)
print("Age:", person.age)
print("City:", person.city)

-- Two ways to access values
print("\n=== Access Methods ===")
print("Dot notation:", person.name)
print("Bracket notation:", person["name"])

-- Bracket notation allows dynamic keys
local key = "age"
print("Dynamic key:", person[key])

-- Adding new keys
person.phone = "555-1234"
person["country"] = "USA"

print("\n=== After Adding ===")
print("Phone:", person.phone)
print("Country:", person.country)

-- Modifying values
person.age = 26
print("\nNew age:", person.age)

-- Removing keys (set to nil)
person.email = nil
print("Email after removal:", person.email)  -- nil

-- Iterating with pairs
print("\n=== Iteration ===")
for key, value in pairs(person) do
    print(key, "=", value)
end

-- Nested dictionaries
local company = {
    name = "TechCorp",
    address = {
        street = "123 Main St",
        city = "San Francisco",
        zip = "94102"
    },
    employees = 50
}

print("\n=== Nested Dictionary ===")
print("Company:", company.name)
print("Street:", company.address.street)
print("City:", company.address.city)

-- Dictionary of dictionaries
local users = {
    user1 = {name = "Alice", role = "admin"},
    user2 = {name = "Bob", role = "user"},
    user3 = {name = "Charlie", role = "moderator"}
}

print("\n=== Dictionary of Dictionaries ===")
for userId, userData in pairs(users) do
    print(userId .. ":", userData.name, "-", userData.role)
end

-- Checking if key exists
if person.name then
    print("\nName exists:", person.name)
end

if person.email == nil then
    print("Email does not exist")
end

-- Counting keys
local function countKeys(tbl)
    local count = 0
    for _ in pairs(tbl) do
        count = count + 1
    end
    return count
end

print("\nNumber of keys in person:", countKeys(person))

-- Merging dictionaries
local defaults = {theme = "dark", lang = "en"}
local settings = {theme = "light"}

local function merge(t1, t2)
    local result = {}
    for k, v in pairs(t1) do
        result[k] = v
    end
    for k, v in pairs(t2) do
        result[k] = v  -- Overwrites if exists
    end
    return result
end

local config = merge(defaults, settings)
print("\n=== Merged Config ===")
for k, v in pairs(config) do
    print(k, "=", v)
end

-- Keys can be any type (except nil)
local weird = {
    [1] = "number key",
    ["string"] = "string key",
    [true] = "boolean key",
    [{}] = "table key"
}

print("\n=== Various Key Types ===")
print("Number key:", weird[1])
print("String key:", weird["string"])
print("Boolean key:", weird[true])

Output

Click Run to execute your code

Mixed Tables

Tables can have both numeric and string keys:

local mixed = {
    "first",      -- [1]
    "second",     -- [2]
    name = "Alice",
    age = 25,
    "third"       -- [3]
}

print(mixed[1])      -- first
print(mixed[2])      -- second
print(mixed[3])      -- third
print(mixed.name)    -- Alice
print(mixed.age)     -- 25
print(#mixed)        -- 3 (only counts numeric indices)

Tip: While mixed tables are possible, it's usually clearer to keep arrays and dictionaries separate for better code readability.

Nested Tables

Tables can contain other tables:

local company = {
    name = "Tech Corp",
    employees = {
        {name = "Alice", role = "Developer"},
        {name = "Bob", role = "Designer"},
        {name = "Charlie", role = "Manager"}
    },
    location = {
        city = "San Francisco",
        state = "CA",
        coordinates = {
            lat = 37.7749,
            lon = -122.4194
        }
    }
}

-- Access nested values
print(company.name)                      -- Tech Corp
print(company.employees[1].name)         -- Alice
print(company.location.city)             -- San Francisco
print(company.location.coordinates.lat)  -- 37.7749