Explicitly warn about lua_next missing an order guarantee in the reference manual

[Lars Müller]

I recently, by accident, stumbled upon an incorrect use of lua_next in a codebase to read a list of strings in order.

I then grepped for lua_next to find similar mistakes and sure enough, there were about two dozen of them.

In fact the majority of the uses of lua_next were subtly incorrect in that they relied on it traversing the table in order.

(This rarely results in bugs in practice since most tables happily live in the array part,

but I imagine that when it does result in a bug, someone is pulling their hair out.)

Now, most of these occurrences were about a decade old.

So I checked the Lua 5.1 reference manual to see whether there was any indication

that the iteration order of lua_next must not be relied upon, but there was not; not even a reference to next().
I also checked the 5.5 reference manual, but the situation is still similar.
Curiously, there is an explicit warning for another caveat:

"See function next for the caveats of modifying the table during its traversal."

... which I would consider a much more rare ocurrence, but at least next() is now referenced.

I suggest adding an explicit warning along the lines of

"The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numerical order, use a for loop and lua_rawgeti / lua_gettable.)"

analogeous to the explicit warning in the documentation of next().

For any experienced Lua programmer, "next" of course rings a bell, and it should be obvious that there is no order guarantee.

But for a C programmer skimming the documentation, there is no such indication, and clearly not all make the connection.

(Finally, in anticipation of "with great power comes great responsibility":
The documentation for lua_next is clearly meant to be helpful rather than terse.

It includes a helpful example and a warning for an (in my opinion) more obscure edge case.
I think it would be great if it also included this more important warning,

so bugs like this are less frequent in the future.

Best regards,
Lars

[Sainan]

> The order in which the indices are enumerated is not specified, even for numeric indices.

Well, the order is guaranteed for numeric indecies, as long as those numeric indecies start at 1 and increment from there. :^)

-- Sainan

[Javier Guerra Giraldez]

On Wed, 15 Apr 2026 at 19:00, 'Sainan' via lua-l <lu...@googlegroups.com> wrote:

> The order in which the indices are enumerated is not specified, even for numeric indices.

Well, the order is guaranteed for numeric indecies, as long as those numeric indecies start at 1 and increment from there. :^)

only if the numeric indices are actually in the non-guaranteed array part (which is an optimisation and not part of the spec)

and only for the current implementation (and all implementations so far that share that specific array-part optimisation)

it's easy to imagine a new implementation that goes through the array part in reverse order, and possibly do the hash part before the array.  that would be just as spec-compliant as the current one and would break all that code that depends on the enumeration order.

 

--

Javier

[Sainan]

What spec? Lua isn't WASM.

-- Sainan

[Lars Müller]

As said, this bug often does not surface because most lists live in the array part, as they ideally should. (I originally said tables, should have said lists to be precise.)

But if you populate a table in a nonstandard order, or using the right table constructor syntax, you will get lists that partially or fully live in the hash part.

For example, see what happens when you iterate the table {[1] = 1, [2] = 2, [3] = 3}

using pairs() on PUC Lua (if you get the expected order, maybe retry a few times, or add more entries).

For the same reason we tell Lua programmers not to expect pairs() to iterate a table in order,

we should tell C programmers not to expect lua_next() to iterate a table in order.

And as said, I think that it would be highly beneficial if a sentence or two to that effect

were added to the section on lua_next() in the reference manual.

So I hope one of the Lua authors sees this and updates it.

- Lars

On Thu, Apr 16 2026 at 00:00:47 +00:00:00, 'Sainan' via lua-l <lu...@googlegroups.com> wrote:

The order in which the indices are enumerated is not specified, even for numeric indices.

Well, the order is guaranteed for numeric indecies, as long as those numeric indecies start at 1 and increment from there. :^) -- Sainan

--

You received this message because you are subscribed to the Google Groups "lua-l" group. To unsubscribe from this group and stop receiving emails from it, send an email to lua-l+un...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/lua-l/z2n0lQNJMcdKCs-h5cMV__eyE2tlgKPNxj_wU2jRgQPs5KEdGTVusWTRIU-kTpQvMnVj07A4wng9WZX9oO3kXnSVGNnv_KwlLZbaEqAeeL8%3D%40calamity.inc.