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

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 
<https://www.lua.org/manual/5.5/manual.html#pdf-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


-- 
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 [email protected].
To view this discussion visit https://groups.google.com/d/msgid/lua-l/H06KDT.F50HP47XVQ6T2%40gmx.de.