The reference guide really answers this question. I am quoting the Lua 5.2 reference manual, but a similar text is contained in the 5.1 manual. However, the manual is very short. It is rare for a single fact to be recounted in more than one sentence. In addition, you often have to juxtapose the facts set out in widely divided sections to understand the deeper implications of the API function.
This is not a defect, it is by design. This is a reference guide to the language, and therefore its main purpose is to fully (and correctly) describe the language.
For more information on the “how” and “why,” the general tip should also read Programming in Lua . The online copy is getting pretty long in the tooth, as it describes Lua 5.0. The current issue of the magazine describes Lua 5.1, and the new edition describes Lua 5.2. However, even the first edition is a good resource if you also pay attention to what has changed in the language since version 5.0.
The reference manual has enough to say about the luaL_check* family of functions.
Each documentation block for entering the API is accompanied by a token that describes its use of the stack, and under what conditions (if any) it throws an error. These tokens are described in section 4.8 :
Each function has the following indicator: [-o, +p, x]
The first field, o, is the number of elements that the function takes off from the stack. The second field, p, is how many elements the function pushes onto the stack. (Any function always pushes its results after popping up its arguments.) A field of the form x | y means that the function can push (or pop) x or y elements, depending on the situation; interrogation mark '?' means that we cannot know how many elements the pops / push function is, looking only at its arguments (for example, they may depend on what is on the stack). The third field, x, indicates whether the function will cause errors: '-' means that the function never causes any errors; "E" means that the function may cause errors; 'v' means that the function may error with the target.
In the chapter of chapter 5, which documents the auxiliary library as a whole (all functions in the official API, whose names begin with luaL_ , and not just lua_ ), we find the following:
Several functions in the helper library are used to test C function arguments. Since the error message is formatted for arguments (for example, "bad argument # 1"), you should not use these functions for other stack values.
Functions called luaL_check * always throw an error if the check is not satisfied.
The luaL_checknumber function luaL_checknumber documented using the token [-0,+0,v] , which means that it does not interfere with the stack (pushes nothing and pushes nothing) and that it can intentionally throw an error.
Other functions that have more specific numeric types differ mainly in the signature of the function. All of them are described similarly. luaL_checkint() "Checks whether the argument to the arg function is a number and returns that number other than int ", changing the type named in the cast, if necessary.
The lua_tonumber() function is described by the token [-0,+0,-] , which means that it does not affect the stack and does not cause any errors. It is documented to return a numeric value from a specified stack index, or 0 if the stack index does not contain something sufficiently numeric. The use of the more general lua_tonumberx() function is lua_tonumberx() , which also provides a flag indicating whether it successfully converted the number or not.
He also has names of sisters with more specific numerical types that do all the same conversions, but bring their results.
Finally, you can also refer to the source code with the understanding that the manual describes the language as it should be, while the source is a specific implementation of this language and may have errors or may reveal implementation details that may change in future versions .
The source luaL_checknumber() is located in lauxlib.c . It can be seen that it is implemented in terms of lua_tonumberx() and the internal function tagerror() , which calls typerror() , which is implemented using luaL_argerror() to actually discard the formatted error message.