Lua uses a virtual stack to pass values to and from C.
Each element in this stack represents a Lua value
(nil, number, string, etc.).
Whenever Lua calls C, the called function gets a new stack,
which is independent of previous stacks and of stacks of
C functions that are still active.
This stack initially contains any arguments to the C function
and it is where the C function pushes its results
to be returned to the caller (see lua_CFunction ).
For convenience,
most query operations in the API do not follow a strict stack discipline.
Instead, they can refer to any element in the stack
by using an index:
A positive index represents an absolute stack position
(starting at 1);
a negative index represents an offset relative to the top of the stack.
More specifically, if the stack has n elements,
then index 1 represents the first element
(that is, the element that was pushed onto the stack first)
and
index n represents the last element;
index -1 also represents the last element
(that is, the element at the top)
and index -n represents the first element.
We say that an index is valid
if it lies between 1 and the stack top
(that is, if 1 ≤ abs(index) ≤ top ). |