What does the [x, y, z]
section mean in the Lua docs? You see it on every C function.
For example, lua_gettop says:
int lua_gettop (lua_State *L);
[-0, +0, –]
Returns the index of the top element in the stack. Because indices start at 1, this result is equal to the number of elements in the stack; in particular, 0 means an empty stack.
What does [-0, +0, –]
mean?
The [-0, +0, –]
section tells you how that function manipulates the Lua argument stack. There's an explanation in the Functions and Types section, but their wall of text is a bit hard to parse. I'll summarize.
Given:
[-o, +p, x]
Those elements mean:
o
: how many elements the function pops from the stack.
-
because it reduces the size of the stack.p
: how many elements the function pushes onto the stack.
+
because it increases the size of the stack.x|y
means the function can push or pop x
or y
elements, depending on the situation;?
means that we cannot know how many elements the function pops/pushes by looking only at its arguments. (For instance, they may depend on what is in the stack.)x
: whether the function may raise errors:
-
means the function never raises any error;m
means the function may raise only out-of-memory errors;v
means the function may raise the errors explained in the text;e
means the function can run arbitrary Lua code, either directly or through metamethods, and therefore may raise any errors.