Next: 5.3 Manipulating Lua Objects Up: 5 The Application Program Previous: 5.1 Executing Lua Code

5.2 Converting Values between C and Lua

Because Lua has no static type system, all values passed between Lua and C have type lua_Object, which works like an abstract type in C that can hold any Lua value.

Lua has automatic memory management, and garbage collection. Because of that, a lua_Object has a limited scope, and is only valid inside the block where it was created. A C function called from Lua is a block, and its parameters are valid only until its end. A good programming practice is to convert Lua objects to C values as soon as they are available, and never to store lua_Objects in C global variables.

When C code calls Lua repeatedly, as in a loop, objects returned by these calls accumulate, and may create a memory problem. To avoid this, nested blocks can be defined with the functions:

void           lua_beginblock           (void);
void           lua_endblock             (void);
After the end of the block, all lua_Object's created inside it are released.

To check the type of a lua_Object, the following function is available:

int            lua_type                 (lua_Object object);
plus the following macros:
int            lua_isnil                (lua_Object object);
int            lua_isnumber             (lua_Object object);
int            lua_isstring             (lua_Object object);
int            lua_istable              (lua_Object object);
int            lua_iscfunction          (lua_Object object);
int            lua_isuserdata           (lua_Object object);
All macros return 1 if the object has the given type, and 0 otherwise.

The function lua_type can be used to distinguish between different kinds of user data; see below.

To translate a value from type lua_Object to a specific C type, the programmer can use:

double         lua_getnumber            (lua_Object object);
char          *lua_getstring            (lua_Object object);
lua_CFunction  lua_getcfunction         (lua_Object object);
void          *lua_getuserdata          (lua_Object object);
lua_getnumber converts a lua_Object to a float. This lua_Object must be a number or a string convertible to number (see Section 4.2); otherwise, the function returns 0.

lua_getstring converts a lua_Object to a string (char *). This lua_Object must be a string or a number; otherwise, the function returns 0 (the null pointer). This function does not create a new string, but returns a pointer to a string inside the Lua environment. Because Lua has garbage collection, there is no guarantee that such pointer will be valid after the block ends.

lua_getcfunction converts a lua_Object to a C function. This lua_Object must have type CFunction; otherwise, the function returns 0 (the null pointer). The type lua_CFunction is explained in Section 5.5.

lua_getuserdata converts a lua_Object to void*. This lua_Object must have type userdata; otherwise, the function returns 0 (the null pointer).

The reverse process, that is, passing a specific C value to Lua, is done by using the following functions:

void           lua_pushnumber           (double n);
void           lua_pushstring           (char *s);
void           lua_pushliteral          (char *s);
void           lua_pushcfunction        (lua_CFunction f);
void           lua_pushusertag          (void *u, int tag);
plus the macro:
void           lua_pushuserdata         (void *u);
All of them receive a C value, convert it to a correspondent lua_Object, and leave the result on the top of the Lua stack, where it can be assigned to a Lua variable, passed as paramenter to a Lua function, etc (see below). lua_pushliteral is like lua_pushstring, but also puts the string in the Lua literal table. This avoids the string to be garbage collected, and therefore has a better overall performance. As a rule, when the string to be pushed is a literal, lua_pushliteral should be used.

User data can have different tags, whose semantics are defined by the host program. Any positive integer can be used to tag a user data. When a user data is retrieved, the function lua_type can be used to get its tag.

To complete the set, the value nil or a lua_Object can also be pushed onto the stack, with:

void           lua_pushnil              (void);
void           lua_pushobject           (lua_Object object);


Next: 5.3 Manipulating Lua Objects Up: 5 The Application Program Previous: 5.1 Executing Lua Code