Arrays vs Dictionaries in Lua

In many languages, arrays and dictionaries (or hash maps) are distinct types with different performance characteristics and APIs. Lua collapses both concepts into the single table type: an 'array' is simply a table whose keys are the consecutive integers 1, 2, 3, ... n, while a 'dictionary' (or 'hash map') is a table whose keys are arbitrary values such as strings. Internally, the Lua reference implementation actually optimizes this by storing the dense integer-keyed part in a contiguous array segment and everything else in a hash segment, but from the programmer's perspective it is one uniform table.

An array-style table stores elements under consecutive integer keys starting at 1, such as local fruits = {'apple', 'banana', 'cherry'}, where fruits[1] is 'apple', fruits[2] is 'banana', and so on. The dedicated iterator ipairs(t) is built for this style: it walks i = 1, 2, 3, ... and stops as soon as it hits the first nil, which makes it fast and predictable but also means it will silently ignore anything after a gap. Array-style tables are the natural fit for ordered collections like queues, stacks, and lists where position matters more than named lookup.

A dictionary-style table stores values under keys that are not a dense integer sequence -- most commonly strings -- such as local player = {name = 'Aria', level = 12, class = 'Mage'}. Fields are read with dot or bracket notation, and the whole table is walked with pairs(t), which visits every key regardless of type but makes no guarantee about the order of iteration. Dictionary-style tables are the natural fit for records and configuration objects, where each piece of data has a meaningful name rather than a meaningful position.

A single table can legitimately combine both styles -- an array of items plus a couple of named metadata fields is common and safe, since ipairs simply ignores the non-integer keys and pairs sees everything. The real danger is creating holes inside the array part, for example {[1] = 'a', [3] = 'c'} with no key 2: ipairs will stop after index 1 and never see 'c', even though the key exists and pairs would find it. Because of this, code that expects array semantics should always build the sequence with table.insert or consecutive assignment, never by skipping indices.