5.1 – Functions and Types

Here we list all functions and types from the auxiliary library in alphabetical order.

luaL_addchar

[-?, +?, m]

void luaL_addchar (luaL_Buffer *B, char c);

Adds the byte c to the buffer B (see luaL_Buffer).

luaL_addgsub

[-?, +?, m]

const void luaL_addgsub (luaL_Buffer *B, const char *s,
                         const char *p, const char *r);

Adds a copy of the string s to the buffer B (see luaL_Buffer), replacing any occurrence of the string p with the string r.

luaL_addlstring

[-?, +?, m]

void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);

Adds the string pointed to by s with length l to the buffer B (see luaL_Buffer). The string can contain embedded zeros.

luaL_addsize

[-?, +?, –]

void luaL_addsize (luaL_Buffer *B, size_t n);

Adds to the buffer B a string of length n previously copied to the buffer area (see luaL_prepbuffer).

luaL_addstring

[-?, +?, m]

void luaL_addstring (luaL_Buffer *B, const char *s);

Adds the zero-terminated string pointed to by s to the buffer B (see luaL_Buffer).

luaL_addvalue

[-?, +?, m]

void luaL_addvalue (luaL_Buffer *B);

Adds the value on the top of the stack to the buffer B (see luaL_Buffer). Pops the value.

This is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be added to the buffer.

luaL_argcheck

[-0, +0, v]

void luaL_argcheck (lua_State *L,
                    int cond,
                    int arg,
                    const char *extramsg);

Checks whether cond is true. If it is not, raises an error with a standard message (see luaL_argerror).

luaL_argerror

[-0, +0, v]

int luaL_argerror (lua_State *L, int arg, const char *extramsg);

Raises an error reporting a problem with argument arg of the C function that called it, using a standard message that includes extramsg as a comment:

     bad argument #arg to 'funcname' (extramsg)

This function never returns.

luaL_argexpected

[-0, +0, v]

void luaL_argexpected (lua_State *L,
                       int cond,
                       int arg,
                       const char *tname);

Checks whether cond is true. If it is not, raises an error about the type of the argument arg with a standard message (see luaL_typeerror).

luaL_Buffer

typedef struct luaL_Buffer luaL_Buffer;

Type for a string buffer.

A string buffer allows C code to build Lua strings piecemeal. Its pattern of use is as follows:

• First declare a variable b of type luaL_Buffer.
• Then initialize it with a call luaL_buffinit(L,&b).
• Then add string pieces to the buffer calling any of the luaL_add* functions.
• Finish by calling luaL_pushresult(&b). This call leaves the final string on the top of the stack.

If you know beforehand the maximum size of the resulting string, you can use the buffer like this:

• First declare a variable b of type luaL_Buffer.
• Then initialize it and preallocate a space of size sz with a call luaL_buffinitsize(L,&b,sz).
• Then produce the string into that space.
• Finish by calling luaL_pushresultsize(&b,sz), where sz is the total size of the resulting string copied into that space (which may be less than or equal to the preallocated size).

During its normal operation, a string buffer uses a variable number of stack slots. So, while using a buffer, you cannot assume that you know where the top of the stack is. You can use the stack between successive calls to buffer operations as long as that use is balanced; that is, when you call a buffer operation, the stack is at the same level it was immediately after the previous buffer operation. (The only exception to this rule is luaL_addvalue.) After calling luaL_pushresult, the stack is back to its level when the buffer was initialized, plus the final string on its top.

luaL_buffaddr

[-0, +0, –]

char *luaL_buffaddr (luaL_Buffer *B);

Returns the address of the current content of buffer B (see luaL_Buffer). Note that any addition to the buffer may invalidate this address.

luaL_buffinit

[-0, +?, –]

void luaL_buffinit (lua_State *L, luaL_Buffer *B);

Initializes a buffer B (see luaL_Buffer). This function does not allocate any space; the buffer must be declared as a variable.

luaL_bufflen

[-0, +0, –]

size_t luaL_bufflen (luaL_Buffer *B);

Returns the length of the current content of buffer B (see luaL_Buffer).

luaL_buffinitsize

[-?, +?, m]

char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);

Equivalent to the sequence luaL_buffinit, luaL_prepbuffsize.

luaL_buffsub

[-?, +?, –]

void luaL_buffsub (luaL_Buffer *B, int n);

Removes n bytes from the buffer B (see luaL_Buffer). The buffer must have at least that many bytes.