How to iterate over tables in Lua

In the Lua programming language, an array is called a table. A table is used in Lua to store data. If you’re storing a lot of data in a structured way, it’s useful to know your options for retrieving that data when you need it.

Creating a table in Lua

To create a table in Lua, you instantiate the table with an arbitrary name:

 mytable = {}

There are different ways you can structure your data in a table. You could fill it with values, essentially creating a list (called a list in some languages):

 mytable = { 'zombie', 'apocalypse' }

Or you could create an associated array (called a map or dictionary in some languages). You can add arbitrary keys to the table using dot notation. You can also add a value to that key the same way you add a value to a variable:

 
myarray = {}
 myarray.baz = 'happy'
 myarray.qux = 'halloween'

You can add verification with the assert() function:

 
assert(myarray.baz == 'happy', 'unexpected value in myarray.baz')
assert(myarray.qux == 'halloween', 'unexpected value in myarray.qux')

You now have two tables: a list-style mytable and an associative array-style myarray.

Iterating over a table with pairs

Lua’s pairs() function extracts key and value pairs from a table.

 
print('pairs of myarray:')

for k,v in pairs(myarray) do
   print(k,v)
 end

Here’s the output:

 
pairs of myarray:
 baz     happy
 qux     halloween

If there are no keys in a table, Lua uses an index. For instance, the mytable table contains the values zombie and apocalypse. It contains no keys, but Lua can improvise:

 
print('pairs of mytable:')

for k,v in pairs(mytable) do
   print(k,v)
 end

Here’s the output:

 
1   zombie
2   apocalypse

Iterating over a table with ipairs

To account for the fact that tables without keys are common, Lua also provides the ipairs function. This function extracts the index and the value:

 
print('ipairs of mytable:')

for i,v in ipairs(mytable) do
   print(i,v)
 end

The output is, in this case, the same as the output of pairs:

 
1   zombie
2   apocalypse

However, watch what happens when you add a key and value pair to mytable:

 
mytable.surprise = 'this value has a key'

 print('ipairs of mytable:')

for i,v in ipairs(mytable) do
   print(i,v)
 end

Lua ignores the key and value because ipairs retrieves only indexed entries:

 
1   zombie
2   apocalypse

The key and value pair, however, have been stored in the table:

 
print('pairs of mytable:')

for k,v in ipairs(mytable) do
   print(k,v)
 end

The output:

 
1          zombie
2          apocalypse
 surprise   this value has a key

Retrieving arbitrary values

You don’t have to iterate over a table to get data out of it. You can call arbitrary data by either index or key:

 
print('call by index:')
 print(mytable[2])
 print(mytable[1])
 print(myarray[2])
 print(myarray[1])

 print('call by key:')
 print(myarray['qux'])
 print(myarray['baz'])
 print(mytable['surprise'])

The output:

 
call by index:
 apocalypse
 zombie
 nil
 nil

 call by key:
 halloween
 happy
 this value has a key

Data structures

Sometimes using a Lua table makes a lot more sense than trying to keep track of dozens of individual variables. Once you understand how to structure and retrieve data in a language, you’re empowered to generate complex data in an organized and safe way.