Extensions

-LuaJIT is fully upwards-compatible with Lua 5.1. It supports all -» standard Lua -library functions and the full set of -» Lua/C API -functions. -

-LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic -loader level. This means you can compile a C module against the -standard Lua headers and load the same shared library from either Lua -or LuaJIT. -

-LuaJIT extends the standard Lua VM with new functionality and adds -several extension modules. Please note this page is only about -functional enhancements and not about performance enhancements, -such as the optimized VM, the faster interpreter or the JIT compiler. -

- -

Extensions Modules

-LuaJIT comes with several built-in extension modules: -

- -

`bit.*` — Bitwise operations

-LuaJIT supports all bitwise operations as defined by -» Lua BitOp: -

-bit.tobit  bit.tohex  bit.bnot    bit.band bit.bor  bit.bxor
-bit.lshift bit.rshift bit.arshift bit.rol  bit.ror  bit.bswap
-

-This module is a LuaJIT built-in — you don't need to download or -install Lua BitOp. The Lua BitOp site has full documentation for all -» Lua BitOp API functions. -The FFI adds support for -64 bit bitwise operations, -using the same API functions. -

-Please make sure to require the module before using any of -its functions: -

-local bit = require("bit")
-

-An already installed Lua BitOp module is ignored by LuaJIT. -This way you can use bit operations from both Lua and LuaJIT on a -shared installation. -

- -

`ffi.*` — FFI library

-The FFI library allows calling external -C functions and the use of C data structures from pure Lua -code. -

- -

`jit.*` — JIT compiler control

-The functions in this module -control the behavior of the JIT compiler engine. -

- -

C API extensions

-LuaJIT adds some -extra functions to the Lua/C API. -

- -

Profiler

-LuaJIT has an integrated profiler. -

- -

Enhanced Standard Library Functions

- -

`xpcall(f, err [,args...])` passes arguments

-Unlike the standard implementation in Lua 5.1, xpcall() -passes any arguments after the error function to the function -which is called in a protected context. -

- -

`loadfile()` etc. handle UTF-8 source code

-Non-ASCII characters are handled transparently by the Lua source code parser. -This allows the use of UTF-8 characters in identifiers and strings. -A UTF-8 BOM is skipped at the start of the source code. -

- -

`tostring()` etc. canonicalize NaN and ±Inf

-All number-to-string conversions consistently convert non-finite numbers -to the same strings on all platforms. NaN results in "nan", -positive infinity results in "inf" and negative infinity results -in "-inf". -

- -

`tonumber()` etc. use builtin string to number conversion

-All string-to-number conversions consistently convert integer and -floating-point inputs in decimal, hexadecimal and binary on all platforms. -strtod() is not used anymore, which avoids numerous -problems with poor C library implementations. The builtin conversion -function provides full precision according to the IEEE-754 standard, it -works independently of the current locale and it supports hex floating-point -numbers (e.g. 0x1.5p-3). -

- -

`string.dump(f [,strip])` generates portable bytecode

-An extra argument has been added to string.dump(). If set to -true, 'stripped' bytecode without debug information is -generated. This speeds up later bytecode loading and reduces memory -usage. See also the --b command line option. -

-The generated bytecode is portable and can be loaded on any architecture -that LuaJIT supports, independent of word size or endianess. However the -bytecode compatibility versions must match. Bytecode stays compatible -for dot releases (x.y.0 → x.y.1), but may change with major or -minor releases (2.0 → 2.1) or between any beta release. Foreign -bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. -

-Note: LJ_GC64 mode requires a different frame layout, which implies -a different, incompatible bytecode format for ports that use this mode (e.g. -ARM64 or MIPS64) or when explicitly enabled for x64. This may be rectified -in the future. -

- -

`table.new(narray, nhash)` allocates a pre-sized table

-An extra library function table.new() can be made available via -require("table.new"). This creates a pre-sized table, just like -the C API equivalent lua_createtable(). This is useful for big -tables if the final table size is known and automatic table resizing is -too expensive. -

- -

`table.clear(tab)` clears a table

-An extra library function table.clear() can be made available -via require("table.clear"). This clears all keys and values -from a table, but preserves the allocated array/hash sizes. This is -useful when a table, which is linked from multiple places, needs to be -cleared and/or when recycling a table for use by the same context. This -avoids managing backlinks, saves an allocation and the overhead of -incremental array/hash part growth. -

-Please note this function is meant for very specific situations. In most -cases it's better to replace the (usually single) link with a new table -and let the GC do its work. -

- -

Enhanced PRNG for `math.random()`

-LuaJIT uses a Tausworthe PRNG with period 2^223 to implement -math.random() and math.randomseed(). The quality of -the PRNG results is much superior compared to the standard Lua -implementation which uses the platform-specific ANSI rand(). -

-The PRNG generates the same sequences from the same seeds on all -platforms and makes use of all bits in the seed argument. -math.random() without arguments generates 52 pseudo-random bits -for every call. The result is uniformly distributed between 0.0 and 1.0. -It's correctly scaled up and rounded for math.random(n [,m]) to -preserve uniformity. -

- -

`io.*` functions handle 64 bit file offsets

-The file I/O functions in the standard io.* library handle -64 bit file offsets. In particular this means it's possible -to open files larger than 2 Gigabytes and to reposition or obtain -the current file position for offsets beyond 2 GB -(fp:seek() method). -

- -

`debug.*` functions identify metamethods

-debug.getinfo() and lua_getinfo() also return information -about invoked metamethods. The namewhat field is set to -"metamethod" and the name field has the name of -the corresponding metamethod (e.g. "__index"). -

- -

Fully Resumable VM

-The LuaJIT VM is fully resumable. This means you can yield from a -coroutine even across contexts, where this would not possible with -the standard Lua 5.1 VM: e.g. you can yield across pcall() -and xpcall(), across iterators and across metamethods. -

- -

Extensions from Lua 5.2

-LuaJIT supports some language and library extensions from Lua 5.2. -Features that are unlikely to break existing code are unconditionally -enabled: -

goto and ::labels::.
Hex escapes '\x3F' and '\*' escape in strings.
load(string|reader [, chunkname [,mode [,env]]]).
loadstring() is an alias for load().
loadfile(filename [,mode [,env]]).
math.log(x [,base]).
string.rep(s, n [,sep]).
string.format(): %q reversible. -%s checks __tostring. -%a and "%A added.
String matching pattern %g added.
io.read("*L").
io.lines() and file:lines() process -io.read() options.
os.exit(status|true|false [,close]).
package.searchpath(name, path [, sep [, rep]]).
package.loadlib(name, "*").
debug.getinfo() returns nparams and isvararg -for option "u".
debug.getlocal() accepts function instead of level.
debug.getlocal() and debug.setlocal() accept negative -indexes for varargs.
debug.getupvalue() and debug.setupvalue() handle -C functions.
debug.upvalueid() and debug.upvaluejoin().
Lua/C API extensions: -lua_version() -lua_upvalueid() -lua_upvaluejoin() -lua_loadx() -lua_copy() -lua_tonumberx() -lua_tointegerx() -luaL_fileresult() -luaL_execresult() -luaL_loadfilex() -luaL_loadbufferx() -luaL_traceback() -luaL_setfuncs() -luaL_pushmodule() -luaL_newlibtable() -luaL_newlib() -luaL_testudata() -luaL_setmetatable() -
Command line option -E.
Command line checks __tostring for errors.

-Other features are only enabled, if LuaJIT is built with --DLUAJIT_ENABLE_LUA52COMPAT: -

goto is a keyword and not a valid variable name anymore.
break can be placed anywhere. Empty statements (;;) -are allowed.
__lt, __le are invoked for mixed types.
__len for tables. rawlen() library function.
pairs() and ipairs() check for __pairs and -__ipairs.
coroutine.running() returns two results.
table.pack() and table.unpack() -(same as unpack()).
io.write() and file:write() return file handle -instead of true.
os.execute() and pipe:close() return detailed -exit status.
debug.setmetatable() returns object.
debug.getuservalue() and debug.setuservalue().
Remove math.mod(), string.gfind().
package.searchers.
module() returns the module table.

-Note: this provides only partial compatibility with Lua 5.2 at the -language and Lua library level. LuaJIT is API+ABI-compatible with -Lua 5.1, which prevents implementing features that would otherwise -break the Lua/C API and ABI (e.g. _ENV). -

- -

Extensions from Lua 5.3

-LuaJIT supports some extensions from Lua 5.3: -

Unicode escape '\u{XX...}' embeds the UTF-8 encoding in string literals.
The argument table arg can be read (and modified) by LUA_INIT and -e chunks.
io.read() and file:read() accept formats with or without a leading *.
assert() accepts any type of error object.
table.move(a1, f, e, t [,a2]).
coroutine.isyieldable().
Lua/C API extensions: -lua_isyieldable() -

- -

C++ Exception Interoperability

-LuaJIT has built-in support for interoperating with C++ exceptions. -The available range of features depends on the target platform and -the toolchain used to compile LuaJIT: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Platform	Compiler	Interoperability
POSIX/x64, DWARF2 unwinding	GCC 4.3+, Clang	Full
ARM `-DLUAJIT_UNWIND_EXTERNAL`	GCC, Clang	Full
Other platforms, DWARF2 unwinding	GCC, Clang	Limited
Windows/x64	MSVC or WinSDK	Full
Windows/x86	Any	Full
Other platforms	Other compilers	No

-Full interoperability means: -

C++ exceptions can be caught on the Lua side with pcall(), -lua_pcall() etc.
C++ exceptions will be converted to the generic Lua error -"C++ exception", unless you use the -C call wrapper feature.
It's safe to throw C++ exceptions across non-protected Lua frames -on the C stack. The contents of the C++ exception object -pass through unmodified.
Lua errors can be caught on the C++ side with catch(...). -The corresponding Lua error message can be retrieved from the Lua stack.
Throwing Lua errors across C++ frames is safe. C++ destructors -will be called.

-Limited interoperability means: -

C++ exceptions can be caught on the Lua side with pcall(), -lua_pcall() etc.
C++ exceptions will be converted to the generic Lua error -"C++ exception", unless you use the -C call wrapper feature.
C++ exceptions will be caught by non-protected Lua frames and -are rethrown as a generic Lua error. The C++ exception object will -be destroyed.
Lua errors cannot be caught on the C++ side.
Throwing Lua errors across C++ frames will not call -C++ destructors.

- -

-No interoperability means: -

It's not safe to throw C++ exceptions across Lua frames.
C++ exceptions cannot be caught on the Lua side.
Lua errors cannot be caught on the C++ side.
Throwing Lua errors across C++ frames will not call -C++ destructors.

-
-

Extensions

Extensions Modules

bit.* — Bitwise operations

ffi.* — FFI library

jit.* — JIT compiler control

C API extensions

Profiler

Enhanced Standard Library Functions

xpcall(f, err [,args...]) passes arguments

loadfile() etc. handle UTF-8 source code

tostring() etc. canonicalize NaN and ±Inf

tonumber() etc. use builtin string to number conversion

string.dump(f [,strip]) generates portable bytecode

table.new(narray, nhash) allocates a pre-sized table

table.clear(tab) clears a table

Enhanced PRNG for math.random()

io.* functions handle 64 bit file offsets

debug.* functions identify metamethods