Re: luaL_error() documented with [-0, +0, v], should be [-0, +1, v] ?

[Roberto Ierusalimschy <roberto@...>]

> at http://www.lua.org/manual/5.2/manual.html#luaL_error the
> luaL_error() function is documented with [-0, +0, v], indicating
> that it does not push anything onto the stack. However, in fact it
> pushes the string with the error message.
> 
> I came across this because in the C++ function that I leave with
> luaL_error(), I use for debugging a very simple stack checker object
> that checks in its destructor if the stack is of the same size as in
> its constructor (plus/minus any expected change).
> 
> Even if lua_error() eventually leaves with a longjmp, the Visual C++
> compilers run the destructors of local objects (http://msdn.microsoft.com/en-us/library/vstudio/yz2ez4as%28v=vs.110%29.aspx),
> so that the stack checker object sees one object more on the stack
> (the error message) than expected.
> 
> As a result, I was wondering if the reference documentation of the
> various luaL_...error() functions shouldn't be changed to say [-0,
> +1, v] instead?

This piece of documentation says how the stack is after the function
returns. As this function never return, the correct entry there
should be neither +0 nor +1, but something like N/A ("does not apply").

The fact that the stack has one extra element when the long jump
(or the exception) happens is an implementation detail, of no
concern for the programmer. A different implementation could
shrink the stack before the jump (instead of after it, as it does
now), with no visible difference for the user.

-- Roberto