1. Lua C Api Table Example
2. Lua C Api Read Table
3. Lua C Api Iterate Table
4. Lua C Api Tablets
5. Lua C Api Create Table

Lua tables can have different behaviors. They can work as arrays, dictionaries, classes, etc. One of the 2 basic behaviors of tables is defined like this. As we have seen, all you have to do is to push the table into the stack, push the index and call luagettable. The -2 argument means that the table is the second element from the top of the stack. Luagettable triggers metamethods. If you do not want to trigger metamethods, use luarawget instead. It uses the same arguments.

The reference manual is the official definition of the Lua language.
For a complete introduction to Lua programming, see the bookProgramming in Lua.

Copyright © 2015–2020 Lua.org, PUC-Rio.Freely available under the terms of theLua license.

Contents

• 1 – Introduction
• 2 – Basic Concepts
  • 2.5 – Garbage Collection
• 3 – The Language
  • 3.3 – Statements
  • 3.4 – Expressions
• 4 – The Application Program Interface
• 5 – The Auxiliary Library
• 6 – Standard Libraries
  • 6.4 – String Manipulation
• 7 – Lua Standalone
• 8 – Incompatibilities with the Previous Version

Index

Lua functions basic _G _VERSION assert collectgarbage dofile error getmetatable ipairs load loadfile next pairs pcall print rawequal rawget rawlen rawset require select setmetatable tonumber tostring type xpcall coroutine coroutine.create coroutine.isyieldable coroutine.resume coroutine.running coroutine.status coroutine.wrap coroutine.yield debug debug.debug debug.gethook debug.getinfo debug.getlocal debug.getmetatable debug.getregistry debug.getupvalue debug.getuservalue debug.sethook debug.setlocal debug.setmetatable debug.setupvalue debug.setuservalue debug.traceback debug.upvalueid debug.upvaluejoin io io.close io.flush io.input io.lines io.open io.output io.popen io.read io.stderr io.stdin io.stdout io.tmpfile io.type io.write file:close file:flush file:lines file:read file:seek file:setvbuf file:write

math math.abs math.acos math.asin math.atan math.ceil math.cos math.deg math.exp math.floor math.fmod math.huge math.log math.max math.maxinteger math.min math.mininteger math.modf math.pi math.rad math.random math.randomseed math.sin math.sqrt math.tan math.tointeger math.type math.ult os os.clock os.date os.difftime os.execute os.exit os.getenv os.remove os.rename os.setlocale os.time os.tmpname package package.config package.cpath package.loaded package.loadlib package.path package.preload package.searchers package.searchpath string string.byte string.char string.dump string.find string.format string.gmatch string.gsub string.len string.lower string.match string.pack string.packsize string.rep string.reverse string.sub string.unpack string.upper table table.concat table.insert table.move table.pack table.remove table.sort table.unpack utf8 utf8.char utf8.charpattern utf8.codepoint utf8.codes utf8.len utf8.offset metamethods __add __band __bnot __bor __bxor __call __concat __div __eq __gc __idiv __index __le __len __lt __metatable __mod __mode __mul __name __newindex __pairs __pow __shl __shr __sub __tostring __unm environment variables LUA_CPATH LUA_CPATH_5_3 LUA_INIT LUA_INIT_5_3 LUA_PATH LUA_PATH_5_3

C API lua_Alloc lua_CFunction lua_Debug lua_Hook lua_Integer lua_KContext lua_KFunction lua_Number lua_Reader lua_State lua_Unsigned lua_Writer lua_absindex lua_arith lua_atpanic lua_call lua_callk lua_checkstack lua_close lua_compare lua_concat lua_copy lua_createtable lua_dump lua_error lua_gc lua_getallocf lua_getextraspace lua_getfield lua_getglobal lua_gethook lua_gethookcount lua_gethookmask lua_geti lua_getinfo lua_getlocal lua_getmetatable lua_getstack lua_gettable lua_gettop lua_getupvalue lua_getuservalue lua_insert lua_isboolean lua_iscfunction lua_isfunction lua_isinteger lua_islightuserdata lua_isnil lua_isnone lua_isnoneornil lua_isnumber lua_isstring lua_istable lua_isthread lua_isuserdata lua_isyieldable lua_len lua_load lua_newstate lua_newtable lua_newthread lua_newuserdata lua_next lua_numbertointeger lua_pcall lua_pcallk lua_pop lua_pushboolean lua_pushcclosure lua_pushcfunction lua_pushfstring lua_pushglobaltable lua_pushinteger lua_pushlightuserdata lua_pushliteral lua_pushlstring lua_pushnil lua_pushnumber lua_pushstring lua_pushthread lua_pushvalue lua_pushvfstring lua_rawequal lua_rawget lua_rawgeti lua_rawgetp lua_rawlen lua_rawset lua_rawseti lua_rawsetp lua_register lua_remove lua_replace lua_resume lua_rotate lua_setallocf lua_setfield lua_setglobal lua_sethook lua_seti lua_setlocal lua_setmetatable lua_settable lua_settop lua_setupvalue lua_setuservalue lua_status lua_stringtonumber lua_toboolean lua_tocfunction lua_tointeger lua_tointegerx lua_tolstring lua_tonumber lua_tonumberx lua_topointer lua_tostring lua_tothread lua_touserdata lua_type lua_typename lua_upvalueid lua_upvalueindex lua_upvaluejoin lua_version lua_xmove lua_yield lua_yieldk

auxiliary library luaL_Buffer luaL_Reg luaL_Stream luaL_addchar luaL_addlstring luaL_addsize luaL_addstring luaL_addvalue luaL_argcheck luaL_argerror luaL_buffinit luaL_buffinitsize luaL_callmeta luaL_checkany luaL_checkinteger luaL_checklstring luaL_checknumber luaL_checkoption luaL_checkstack luaL_checkstring luaL_checktype luaL_checkudata luaL_checkversion luaL_dofile luaL_dostring luaL_error luaL_execresult luaL_fileresult luaL_getmetafield luaL_getmetatable luaL_getsubtable luaL_gsub luaL_len luaL_loadbuffer luaL_loadbufferx luaL_loadfile luaL_loadfilex luaL_loadstring luaL_newlib luaL_newlibtable luaL_newmetatable luaL_newstate luaL_openlibs luaL_opt luaL_optinteger luaL_optlstring luaL_optnumber luaL_optstring luaL_prepbuffer luaL_prepbuffsize luaL_pushresult luaL_pushresultsize luaL_ref luaL_requiref luaL_setfuncs luaL_setmetatable luaL_testudata luaL_tolstring luaL_traceback luaL_typename luaL_unref luaL_where standard library luaopen_base luaopen_coroutine luaopen_debug luaopen_io luaopen_math luaopen_os luaopen_package luaopen_string luaopen_table luaopen_utf8 constants LUA_ERRERR LUA_ERRFILE LUA_ERRGCMM LUA_ERRMEM LUA_ERRRUN LUA_ERRSYNTAX LUA_HOOKCALL LUA_HOOKCOUNT LUA_HOOKLINE LUA_HOOKRET LUA_HOOKTAILCALL LUA_MASKCALL LUA_MASKCOUNT LUA_MASKLINE LUA_MASKRET LUA_MAXINTEGER LUA_MININTEGER LUA_MINSTACK LUA_MULTRET LUA_NOREF LUA_OK LUA_OPADD LUA_OPBAND LUA_OPBNOT LUA_OPBOR LUA_OPBXOR LUA_OPDIV LUA_OPEQ LUA_OPIDIV LUA_OPLE LUA_OPLT LUA_OPMOD LUA_OPMUL LUA_OPPOW LUA_OPSHL LUA_OPSHR LUA_OPSUB LUA_OPUNM LUA_REFNIL LUA_REGISTRYINDEX LUA_RIDX_GLOBALS LUA_RIDX_MAINTHREAD LUA_TBOOLEAN LUA_TFUNCTION LUA_TLIGHTUSERDATA LUA_TNIL LUA_TNONE LUA_TNUMBER LUA_TSTRING LUA_TTABLE LUA_TTHREAD LUA_TUSERDATA LUA_USE_APICHECK LUA_YIELD LUAL_BUFFERSIZE

Last update:Tue Aug 25 13:45:14 UTC 2020

overview · the Lua API · the C API · download · license · back

Overview

luaarray is a module that can serve as a C array to Lua table bridge. It allows the creation of C arrays of any dimensionality from within Lua and its subsequent treatment as if they were normal Lua tables. You can also use the C api to expose a C array from within the host application as a Lua table so it can be of use in the efficient representation and manipulation of structures which are array-like by nature, such as images, sounds or vectors and matrices.

luaarray works with Lua versions 5.1 and 5.2.

The Lua API

To use the module you must first require it as usual:

Lua C Api Table Example

You can explicitly create an array of some type like this:

This creates an array encapsulating a C array of type double[2][2] and initializes it with the elements in a give table. The returned array is a userdata with suitable metamethods so that you can use it in almost any way you would use a normal Lua table, including indexing of specific elements and iteration via pairs and ipairs. You can create arrays of other types by using one of the following istead of array.doubles: array.floats, array.ulongs, array.longs, array.uints, array.ints, array.ushorts, array.shorts, array.uchars, array.chars. The table can also be of any dimensionality providing that its dimensions are consistent. You cannot convert this table to an array for example as it can't be directly and unambiguously mapped to a C array:

In order to facilitate interoperation with modules which pass around arrays as binary data enclosed in strings or light userdata you can convert both of these types to arrays as well but in this case you must explicitly specify the dimensions. For example:

You can ommit the dimensions in the case of strings. The returned array will have one dimension (it will be a vector) of size equal to the size of the array divided by the size in bytes of the data type.

Finally you can also use the most generic form of the array constructors with tables as well. If the dimensionality of the table doesn't match the dimensions specified you'll get an error so this allows easy type checking. For example:

It is not always necessary to explicitly create an array. Most if not all functions operating on such arrays in this as well as other modules that will be built on this accept a normal table in the place of an array. The table is then implicitly promoted to an array of a suitable type. As an example the divide function which divides two arrays element by element can be used in any of the following ways.

The result is always an array of the same type as the arguments, so a float array in the first two cases but a double array in the last.

Apart from division you can perform element-by-element multiplication, addition, substraction, scaling by a constant and raising to a power with array.multiply, array.add, array.subtract, array.scale and array.raise respectively. The latter two accept the scalar as the second argument so array.scale (a, 2) doubles each element of array a, while array.raise (a, 2) squares it. In any case, operating on arrays of incompatible types results in an error.

You can also copy an array with array.copy, which creates an entirely separate copy of the array, allocating new memory for it. To set all elements of an array to some number use array.set. For example array.set (a, 0) initializes the array a, which can be of any dimensionality, to all zero elements.

An array can also be cast to some other dimensionality (in the C sense) with array.cast. This creates a new array of different dimensionality which references the same memory as the initial array. Changing an element in either will be reflected in the other. For example:

You can also use array.slice to slice an array which creates a copy (so it won't reference the elements of the initial array) of the same dimensionality but with only a subrange within each dimension. The array is specified as the first argument and the lowest and highest index of each dimension should be specified in subsequent arguments. For example:

Similarly it is possible to use array.adjust to adjust an array to a predefined dimensionality. If an array is adjusted to a higher dimension it will be padded with extra values which are normally zero. If it needs to be adjusted to a lower dimension some values will be ommited. This may be useful if you need to accept data of a specific dimension but want to be flexible about it.

For instance consider the case where you want to accept colors in RGBA format but you want to be able to accept RGB triplets just as well. In this case one can use:

Of course this will give all RGB triplets a zero alpha value which may not be desirable. In this case it is possible to specify a default array. If the array to be adjusted needs to be padded with extra values then instead of using zeros the respective values of the default array will be used. For instance:

It is possible to adjust arrays of any rank but the rank must remain constant. For example one can use the following code to accept any matrix and pad it to 4 rows by 4 columns:

Note that the array returned by array.adjust is a copy of the original. Adjustment is not carried out in place.

The C API

This module can be used by a host application which embeds Lua as an extension and configuration language as well allowing efficient exporting of internal C arrays for manipulation by the Lua environment. The API is essentially the same as the Lua API outlined above:

voidarray_toarray (lua_State *L, int index, array_Type type, int rank, ...);voidarray_toarrayv (lua_State *L, int index, array_Type type, int rank, int *size);

Push onto the stack an array of the given rank and type initialized by the value at location index in the stack which can be a table, string or light userdata. The rank is the number of dimensions of the array and the length along each dimension is given either as an array of integers (in the case of array_toarrayv or as additional arguments passed after rank. The type can be any of the following constants: ARRAY_TDOUBLE, ARRAY_TFLOAT, ARRAY_TULONG, ARRAY_TLONG, ARRAY_TUINT ARRAY_TINT, ARRAY_TUSHORT, ARRAY_TSHORT, ARRAY_TUCHAR, ARRAY_TCHAR.

array_Array *array_createarrayv (lua_State *L, array_Type type, void *values, int rank, int *size);array_Array *array_createarray (lua_State *L, array_Type type, void *values, int rank, ...);

Push onto the stack a newly created array of the specified rank, type and size and initialize it with the C array (which must be of the same type and size) specified in values. If values is NULL memory is still allocated to hold the elements of the array but it is not initialized to anything. Return a pointer to the newly created array.

voidarray_copy (lua_State *L, int index);

Push onto the stack a copy of the array at stack location index.

voidarray_set (lua_State *L, int index, lua_Number c);

Lua C Api Read Table

Set all elements of the array at stack location index to the number c.

voidarray_cast (lua_State *L, int index, int rank, ...);voidarray_castv (lua_State *L, int index, int rank, int *size);

Push onto the stack an new array which is a cast of the array at location index in the stack. The new array references the same memory as the original array but has different rank and lengths.

voidarray_slicev (lua_State *L, int index, int *slices);

Push onto the stack an new array which is a slice of the array at location index in the stack. The range of elements along each dimension of the slice is give in the array slices.

voidarray_adjust (lua_State *L, int index, void *defaults, int rank, ...);voidarray_adjustv (lua_State *L, int index, void *defaults, int rank, int *size);

Push onto the stack an new array which is an adjusted version of the array at location index in the stack. The new size of the array is either given in the array size (for or array_adjustv) or as a variable (depending on rank) number of arguments (for or array_adjust). Default values are given in the array defaults which should match the array to be adjusted in rank and type.

The following functions are useful if your C API needs to accepts specific types of arrays. They can be used to both check that the supplied arrays are of a specific rank, type or size and in converting arrays supplied as normal Lua tables to proper array objects of the requested kind. The latter behavior facilitates interchangeability between arrays and Lua tables: the user can specify an array as either kind of value and it will be implicitly converted to the right kind of array so that the C API only has to deal with a specific kind of data type.

array_Array *array_testarray (lua_State *L, int index);

Check whether the value at stack location index is an array or a table that can be converted to an array. Return the array in that case otherwise NULL.

array_Array *array_checkarray (lua_State *L, int index);

This is similar to array_testarray only instead of silently returning NULL if the value is not an array it throws an error.

array_Array *array_checkcompatible (lua_State *L, int index, int what, ...);array_Array *array_testcompatible (lua_State *L, int index, int what, ...);

These are similar to the previous functions only in addition to checking whether the value at the location index is an array they can also check whether the supplied array has a specific type, rank or size. What to check for is given in the argument what which is a bitwise OR of any of the following constants: ARRAY_TYPE, ARRAY_RANK, ARRAY_SIZE.

If ARRAY_TYPE is specified, an argument of type array_Type should be passed after what to specify the type of the array (or the type to which a Lua table will be converted). If ARRAY_RANK is specified an integer should be passed with the expected rank of the array and similarly if ARRAY_SIZE is specified a number of integers equal to the expected rank of the array must be passed containing the expected size of each dimension of the table.

Note that if size checking is required rank checking must be required as well, that is you can't specify ARRAY_SIZE, without specifying ARRAY_RANK. Also if more than one kind of checking is required the extra arguments must be passed in the order: type, rank, size.

As an example, to check that a value at location i is an array representing a 4x4 table:

Lua C Api Iterate Table

Download

The latest release of luaarray is 0.1, released on April the 12th 2012. You can download the source here.

Lua C Api Tablets

License

Lua C Api Create Table

luaarray is released under the terms and conditions of the MIT/X11 license.