lua_pop vs lua_remove

Currently I'm building my own script VM manager class in C++. I have no problems with any of the Lua & Lua C or C++ stuff, but the one section that confuses me is when to use lua_pop and when to use lua_remove.

From what I understand, lua_pop is to remove multiple values(on the stack) from the top down, eliminating data that is no longer needed, w开发者_Go百科here as lua_remove is for removing a single value from any arbitrary, valid stack index (basically what the Lua manual says for both :P).

But I've noticed certain segments of code scattered around the web that intermix lua_pop and lua_remove, but when I tried to use lua_pop instead of lua_remove where the call just removed the top stack element, I ran into problems. So would it be possible to get a definitive example or explanation on how and when to use these two functions correctly, as well as relative speed & efficiency for these two? I assume lua_pop is faster than lua_remove, which is one of the reasons why I want to use lua_pop as much as possible, apart from coding 'correct code'.

A typical example of lua_remove is accessing tables. Snippets from Lua reference manual.

lua_getfield(L, LUA_GLOBALSINDEX, "t");   /* table to be indexed */
lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
lua_remove(L, -2);                  /* remove 't' from the stack */

lua_getfield pushes t[x] on the stack. You no longer need t, so you remove it.

A typical example of lua_pop is iterating over a table.

lua_pushnil(L);  /* first key */
while (lua_next(L, t) != 0) {
    /* uses 'key' (at index -2) and 'value' (at index -1) */
    /* do whatever you like with the key and the value */

    lua_pop(L, 1);
}

After you are done with a single iteration, you need to have the key on top of the stack, so that lua_next knows which key/value pair comes next. You need to remove the value, which is on top of the stack.

It's not a definitive example. In Lua you do whatever works for you. Always keep in mind what's on your lua_State stack, and you'll be fine.

The following pieces of C code are entirely equivalent:

lua_pop(L, 1); // same as:
lua_remove(L, -1);

So are these:

lua_pop(L, n); // same as:
lua_settop(L, lua_gettop(L)-n);

They are very different. lua_pop always removes from the top of the stack. lua_remove will remove a value from anywere on the stack. If the value you wish to remove from the stack is not on the top you can't use lua_pop.

e.g.

[5][4][3][2][1]
after lua_pop(L, 3); would be
[X][X][X][2][1]



[5][4][3][2][1]
after lua_remove(L, 3); would be
[X][5][4][2][1]