C API functions and types: concat–gc

lua_concat

[-n, +1, e]

void lua_concat (lua_State *L, int n);

Concatenates the n values at the top of the stack, pops them, and leaves the result on the top. If n is 1, the result is the single value on the stack (that is, the function does nothing); if n is 0, the result is the empty string. Concatenation is performed following the usual semantics of Lua (see §3.4.6).

lua_copy

[-0, +0, –]

void lua_copy (lua_State *L, int fromidx, int toidx);

Copies the element at index fromidx into the valid index toidx, replacing the value at that position. Values at other positions are not affected.

lua_createtable

[-0, +1, m]

void lua_createtable (lua_State *L, int nseq, int nrec);

Creates a new empty table and pushes it onto the stack. Parameter nseq is a hint for how many elements the table will have as a sequence; parameter nrec is a hint for how many other elements the table will have. Lua may use these hints to preallocate memory for the new table. This preallocation may help performance when you know in advance how many elements the table will have. Otherwise you should use the function lua_newtable.

lua_dump

[-0, +0, –]

int lua_dump (lua_State *L,
                        lua_Writer writer,
                        void *data,
                        int strip);

Dumps a function as a binary chunk. Receives a Lua function on the top of the stack and produces a binary chunk that, if loaded again, results in a function equivalent to the one dumped. As it produces parts of the chunk, lua_dump calls function writer (see lua_Writer) with the given data to write them.

The function lua_dump fully preserves the Lua stack through the calls to the writer function, except that it may push some values for internal use before the first call, and it restores the stack size to its original size after the last call.

If strip is true, the binary representation may not include all debug information about the function, to save space.

The value returned is the error code returned by the last call to the writer; 0 means no errors.

lua_error

[-1, +0, v]

int lua_error (lua_State *L);

Raises a Lua error, using the value on the top of the stack as the error object. This function does a long jump, and therefore never returns (see luaL_error).

lua_gc

[-0, +0, –]

int lua_gc (lua_State *L, int what, ...);

Controls the garbage collector.

This function performs several tasks, according to the value of the parameter what. For options that need extra arguments, they are listed after the option.

• LUA_GCCOLLECT: Performs a full garbage-collection cycle.

• LUA_GCSTOP: Stops the garbage collector.

• LUA_GCRESTART: Restarts the garbage collector.

• LUA_GCCOUNT: Returns the current amount of memory (in Kbytes) in use by Lua.

• LUA_GCCOUNTB: Returns the remainder of dividing the current amount of bytes of memory in use by Lua by 1024.

• LUA_GCSTEP (size_t n): Performs a step of garbage collection.

• LUA_GCISRUNNING: Returns a boolean that tells whether the collector is running (i.e., not stopped).

• LUA_GCINC: Changes the collector to incremental mode. Returns the previous mode (LUA_GCGEN or LUA_GCINC).

• LUA_GCGEN: Changes the collector to generational mode. Returns the previous mode (LUA_GCGEN or LUA_GCINC).

• LUA_GCPARAM (int param, int val): Changes and/or returns the value of a parameter of the collector. If val is -1, the call only returns the current value. The argument param must have one of the following values:

  • LUA_GCPMINORMUL: The minor multiplier.
  • LUA_GCPMAJORMINOR: The major-minor multiplier.
  • LUA_GCPMINORMAJOR: The minor-major multiplier.
  • LUA_GCPPAUSE: The garbage-collector pause.
  • LUA_GCPSTEPMUL: The step multiplier.
  • LUA_GCPSTEPSIZE: The step size.

For more details about these options, see collectgarbage.

This function should not be called by a finalizer.