*userdata*
Userdata represents C values in Lua. A full userdata represents a
block of memory. It is an object (like a table): you must create it,
it can have its own metatable, and you can detect when it is being
collected. A full userdata is only equal to itself (under raw
equality).
When Lua collects a full userdata with a `gc` metamethod, Lua calls
the metamethod and marks the userdata as finalized. When this userdata
is collected again then Lua frees its corresponding memory.
lua_next *lua_next()*
>c
int lua_next (lua_State *L, int index);
<
Pops a key from the stack, and pushes a key-value pair from the table
at the given index (the "next" pair after the given key). If there are
no more elements in the table, then `lua_next` returns 0 (and pushes
nothing).
*lua-tabletraversal*
A typical traversal looks like this:
>c
/* table is in the stack at index 't' */
lua_pushnil(L); /* first key */
while (lua_next(L, t) != 0) {
/* uses 'key' (at index -2) and 'value' (at index -1) */
printf("%s - %s\n",
lua_typename(L, lua_type(L, -2)),
lua_typename(L, lua_type(L, -1)));
/* removes 'value'; keeps 'key' for next iteration */
lua_pop(L, 1);
}
<
While traversing a table, do not call `lua_tolstring` (see
|lua_tolstring()|) directly on a key, unless you know that the
key is actually a string. Recall that `lua_tolstring` `changes` the
value at the given index; this confuses the next call to `lua_next`.
lua_Number *lua_Number*
>c
typedef double lua_Number;
<
The type of numbers in Lua. By default, it is double, but that can be
changed in `luaconf.h`.
Through the configuration file you can change Lua to operate with
another type for numbers (e.g., float or long).
lua_objlen *lua_objlen()*
>c
size_t lua_objlen (lua_State *L, int index);
<
Returns the "length" of the value at the given acceptable index: for
strings, this is the string length; for tables, this is the result of
the length operator (`#`); for userdata, this is the size of the
block of memory allocated for the userdata; for other values, it is 0.
lua_pcall *lua_pcall()*
>c
lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
<
Calls a function in protected mode.
Both `nargs` and `nresults` have the same meaning as in `lua_call`
(see |lua_call()|). If there are no errors during the call,
`lua_pcall` behaves exactly like `lua_call`. However, if there is any
error, `lua_pcall` catches it, pushes a single value on the stack (the
error message), and returns an error code. Like `lua_call`,
`lua_pcall` always removes the function and its arguments from the
stack.
If `errfunc` is 0, then the error message returned on the stack is
exactly the original error message. Otherwise, `errfunc` is the stack
index of an `error` `handler function`. (In the current
implementation, this index cannot be a pseudo-index.) In case of
runtime errors, this function will be called with the error message
and its return value will be the message returned on the stack by
`lua_pcall`.
Typically, the error handler function is used to add more debug
information to the error message, such as a stack traceback. Such
information cannot be gathered after the return