API next
Returns the next key/value pair for a given table and key.
key, value = next (table [, current])
Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. next
returns the next index of the table and the value associated with the index. When called with nil as its second argument, next
returns the first index of the table and its associated value. When called with the last index, or with nil in an empty table, next
returns nil. If the second argument is absent, then it is interpreted as nil.
Lua has no declaration of fields; There is no difference between a field not present in a table or a field with value nil. Therefore, next
only considers fields with non-nil values. The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numeric order, use a numerical for or the ipairs
function.)
The behavior of next
is undefined if, during the traversal, you assign any value to a non-existent field in the table. Changing values of existing keys or removing keys is alright though.
References
- Roberto Ierusalimschy, 2003, Chapter 7.3: Stateless Iterators, Programming in Lua, 1st ed