Inserting and Removing

Lua comes with a group of functions for working with lists. Their names start with table., just as the names of the math functions start with math.. The two you'll use most are table.insert and table.remove.

table.insert(list, value) adds the value to the end of the list. It does the same as list[#list + 1] = value, but it's easier to read. With three values in the parentheses, table.insert(list, position, value) puts the value at the given position. The items from that position on move one place to the right, so their indexes go up by one:

local tasks = {"feed the hens", "water the field"}
table.insert(tasks, "milk Bella")
table.insert(tasks, 1, "let Rex out")
print(#tasks)
print(tasks[1])
print(tasks[2])
print(tasks[4])

This prints:

4
let Rex out
feed the hens
milk Bella

The position goes before the value. If you swap them, as in table.insert(tasks, "milk Bella", 1), the program stops with bad argument #2 to 'insert' (number expected, got string): the second value in the parentheses (the second argument) should have been a number. The position must also be between 1 and #tasks + 1. Anything else, such as table.insert(tasks, 10, "rest"), ends with bad argument #2 to 'insert' (position out of bounds). That way, table.insert never leaves a hole.

table.remove(list) removes the last item, and table.remove(list, position) removes the item at that position. The items after it move one place to the left, so there's no hole. Both also give you the removed item back. We say that they return it, just as math.floor returns a rounded number. You can store it in a variable:

local tasks = {"let Rex out", "feed the hens", "milk Bella", "water the field"}
local done = table.remove(tasks, 1)
print("Done: " .. done)
print("Next: " .. tasks[1])
local later = table.remove(tasks)
print("Tomorrow: " .. later)
print("Left: " .. #tasks)

This prints:

Done: let Rex out
Next: feed the hens
Tomorrow: water the field
Left: 2

After the first table.remove, "feed the hens" moved from index 2 to index 1. If you don't need the removed item, just write table.remove(tasks, 1) on a line of its own. Removing from an empty list isn't an error: nothing is removed, and you get nil back.

Compare it with tasks[1] = nil. That only empties the first place and leaves a hole at the start of the list: tasks[1] is then nil, and "Next: " .. tasks[1] ends with attempt to concatenate a nil value. To remove an item, use table.remove.