Editing Lua (section)

=== Tables ===
Tables are the most important data structures (and, by design, the only built-in [[composite data type]]) in Lua and are the foundation of all user-created types. They are associative arrays with addition of automatic numeric key and special syntax.

A table is a set of key and data pairs, where the data is referenced by key; in other words, it is a [[hash table|hashed]] heterogeneous associative array.

Tables are created using the <code>{}</code> constructor syntax.

<syntaxhighlight lang="lua">
a_table = {} -- Creates a new, empty table
</syntaxhighlight>

Tables are always passed by reference (see [[Call by sharing]]).

A key (index) can be any value except <code>nil</code> and [[NaN]], including functions.

<syntaxhighlight lang="lua">
a_table = {x = 10}  -- Creates a new table, with one entry mapping "x" to the number 10.
print(a_table["x"]) -- Prints the value associated with the string key, in this case 10.
b_table = a_table
b_table["x"] = 20   -- The value in the table has been changed to 20.
print(b_table["x"]) -- Prints 20.
print(a_table["x"]) -- Also prints 20, because a_table and b_table both refer to the same table.
</syntaxhighlight>

A table is often used as [[object composition|structure]] (or [[Record (computer science)|record]]) by using [[string (computer science)|strings]] as keys. Because such use is very common, Lua features a special syntax for accessing such fields.<ref>{{cite web|url=https://www.lua.org/manual/5.1/manual.html#2.3|title=Lua 5.1 Reference Manual|access-date=2014-02-27|year=2014}}</ref>

<syntaxhighlight lang="lua">
point = { x = 10, y = 20 }   -- Create new table
print(point["x"])            -- Prints 10
print(point.x)               -- Has exactly the same meaning as line above. The easier-to-read dot notation is just syntactic sugar.
</syntaxhighlight>

By using a table to store related functions, it can act as a namespace.

<syntaxhighlight lang="lua">
Point = {}

Point.new = function(x, y)
  return {x = x, y = y}  --  return {["x"] = x, ["y"] = y}
end

Point.set_x = function(point, x)
  point.x = x  --  point["x"] = x;
end
</syntaxhighlight>

Tables are automatically assigned a numerical key, enabling them to be used as an [[array data type]]. The first automatic index is 1 rather than 0 as it is for many other programming languages (though an explicit index of 0 is allowed).

A numeric key <code>1</code> is distinct from a string key <code>"1"</code>.

<syntaxhighlight lang="lua">
array = { "a", "b", "c", "d" }   -- Indices are assigned automatically.
print(array[2])                  -- Prints "b". Automatic indexing in Lua starts at 1.
print(#array)                    -- Prints 4.  # is the length operator for tables and strings.
array[0] = "z"                   -- Zero is a legal index.
print(#array)                    -- Still prints 4, as Lua arrays are 1-based.
</syntaxhighlight>

The length of a table <code>t</code> is defined to be any integer index <code>n</code> such that <code>t[n]</code> is not <code>nil</code> and <code>t[n+1]</code> is <code>nil</code>; moreover, if <code>t[1]</code> is <code>nil</code>, <code>n</code> can be zero. For a regular array, with non-nil values from 1 to a given <code>n</code>, its length is exactly that <code>n</code>, the index of its last value. If the array has "holes" (that is, nil values between other non-nil values), then <code>#t</code> can be any of the indices that directly precedes a <code>nil</code> value (that is, it may consider any such nil value as the end of the array).<ref>{{cite web|url=https://www.lua.org/manual/5.1/manual.html#2.5.5|title=Lua 5.1 Reference Manual|access-date=2012-10-16|year=2012}}</ref>

<syntaxhighlight lang="lua">
ExampleTable =
{
  {1, 2, 3, 4},
  {5, 6, 7, 8}
}
print(ExampleTable[1][3]) -- Prints "3"
print(ExampleTable[2][4]) -- Prints "8"
</syntaxhighlight>

A table can be an array of objects.

<syntaxhighlight lang="lua">
function Point(x, y)        -- "Point" object constructor
  return { x = x, y = y }   -- Creates and returns a new object (table)
end
array = { Point(10, 20), Point(30, 40), Point(50, 60) }   -- Creates array of points
                        -- array = { { x = 10, y = 20 }, { x = 30, y = 40 }, { x = 50, y = 60 } };
print(array[2].y)                                         -- Prints 40
</syntaxhighlight>

Using a hash map to emulate an array is normally slower than using an actual array; however, Lua tables are optimized for use as arrays to help avoid this issue.<ref name=lobject_h_array>{{cite web|url=https://www.lua.org/source/5.1/lobject.h.html#array|title=Lua 5.1 Source Code|access-date=2011-03-24|year=2006}}</ref><!-- I'd like to find a message on the mailing list from one of the developers, but I can't. However, source code is a reasonably trustworthy reference. -->