LuaJIT standard library#

Every name a checked program can use without declaring it, and every module LuaJIT loads by name, as the compiler itself declares them. nupp reads these files to decide what a call means, so a signature here is the signature the checker enforces.

Globals#

The functions and values a program can name anywhere. Their declarations are loaded before any source is checked, so nothing requires them and nothing can shadow them by accident.

assertfunction#

local assert: function<T>(takes v: T?, msg: any?): T preserves v

Raises msg when v is nil or false, and otherwise returns v.

Type parameters#

Arguments#

Returns#

collectgarbagefunction#

local collectgarbage: function(): number
& function(opt: 'collect' | 'stop' | 'restart' | 'count' | 'setpause' | 'setstepmul', arg: number?): number
& function(opt: 'step' | 'isrunning', arg: number?): boolean

Controls the garbage collector. opt is "collect" for a full cycle, the default, or "stop", "restart", "count", "step", "setpause", "setstepmul" or "isrunning".

Arguments#

Returns#

dofilefunction#

local dofile: function(path: string?): any

Loads and runs the file at path, or standard input when it is omitted. Errors from the chunk propagate to the caller.

Arguments#

Returns#

errorfunction#

local error: @nosuspend function(msg: any, level: number?): never

Raises msg as an error, unwinding to the nearest pcall. A string message is prefixed with a source position chosen by level: 1, the default, blames the caller of error, 2 blames its caller in turn, and 0 adds no position at all.

Arguments#

Returns#

gcinfofunction#

local gcinfo: function(): integer

Returns the amount of memory in use, in kilobytes. Superseded by collectgarbage("count").

Returns#

getfenvfunction#

local getfenv: function(f: any?): table

Returns the environment a function sees as its globals, addressed the way setfenv addresses one.

Arguments#

Returns#

getmetatablefunction#

local getmetatable: function<T>(v: T): metatable<T>?

Returns the metatable of v, or the value of its __metatable field when it has one, or nil when there is no metatable.

Type parameters#

Arguments#

Returns#

ipairsfunction#

const ipairs: @nosuspend function<V>(borrows t: const{V}): @nosuspend function(): ((integer, V) | (nil)) borrows (t)

Returns an iterator over the array part of t, from index 1 up to the first missing element.

when done

Type parameters#

Arguments#

Returns#

loadfunction#

local load: function(chunk: any, name: string?, mode: string?, env: table?): (any, string?)

Compiles a chunk read piecewise from chunk, a function returning successive pieces of source, without running it.

Arguments#

Returns#

loadfilefunction#

local loadfile: function(path: string?, mode: string?, env: table?): (any, string?)

Compiles the file at path, or standard input when it is omitted, without running it.

Arguments#

Returns#

loadstringfunction#

local loadstring: function(s: string, name: string?): (any, string?)

Compiles the string s as a chunk, without running it.

Arguments#

Returns#

newproxyfunction#

local newproxy: function(mt: any?): userdata

Creates a userdata with a fresh empty metatable, with no metatable, or sharing the metatable of an existing proxy.

Arguments#

Returns#

nextfunction#

local next: @nosuspend function(t: table, k: any?): (any, any)

Returns the pair that follows key k in t. Passing nil, or omitting k, returns the first pair; the traversal order is unspecified.

Arguments#

Returns#

pairsfunction#

local pairs: @nosuspend function<K, V>(
    borrows t: {@readonly [K]: V}
): @nosuspend function(): ((K, V) | (nil)) borrows (t)

Returns an iterator over every key/value pair of t, in unspecified order. New keys must not be added to t during the traversal.

Type parameters#

Arguments#

Returns#

pcallfunction#

local pcall: function<A..., R...>(scoped f: function(A...): R..., A...): ((true, R...) | (false, unknown))
& function<A..., R...>(takes f: function(A...): R..., A...): ((true, R...) | (false, unknown))

Calls f with the given arguments, trapping any error it raises.

so has to be narrowed or cast before it is used as anything in particular

Type parameters#

Arguments#

Returns#

printfunction#

local print: @nosuspend function(borrows ...: any)

Writes every argument to standard output, converted with tostring, separated by tabs and followed by a newline.

Arguments#

rawequalfunction#

local rawequal: @nosuspend function(borrows a: any, borrows b: any): boolean

Compares two values for primitive equality, without an __eq metamethod.

Arguments#

Returns#

rawgetfunction#

local rawget: @nosuspend function(t: table, k: any): any

Reads t[k] without consulting an __index metamethod.

Arguments#

Returns#

rawlenfunction#

local rawlen: @nosuspend function(borrows v: any): integer

Returns the length of a table or string without consulting a __len metamethod.

Arguments#

Returns#

rawsetfunction#

local rawset: @nosuspend function(t: table, k: any, v: any): table

Assigns t[k] = v without consulting a __newindex metamethod.

Arguments#

Returns#

requirefunction#

local require: function(name: string): any

Loads module name the first time it is asked for and returns its value. Later calls hand back the value cached in package.loaded.

A call through the unshadowed builtin with a literal name is resolved by the checker to the module's declared type, and one with a computed name returns unknown in a Nupp file. The any declared here is what a plain Lua file gets for a computed name, and what any call through a shadowing binding gets.

Arguments#

Returns#

selectfunction#

local select: function<A...>(n: '#', A...): integer & function<A...>(n: number, A...): A...

Selects from a vararg list. With a number, returns every argument from the nth onwards, counting from the end when n is negative; with "#", returns how many arguments follow.

Type parameters#

Arguments#

Returns#

setfenvfunction#

local setfenv: function(f: any, env: table): any

Sets the environment a function sees as its globals. f is the function itself, or a stack level: 1 is the caller, 0 the running thread.

Arguments#

Returns#

setmetatablefunction#

local setmetatable: function<T>(takes t: T, mt: metatable<T>?): T preserves t

Sets t's metatable, or removes it when mt is nil. Raises when the current metatable has a __metatable field.

Type parameters#

Arguments#

Returns#

tonumberfunction#

local tonumber: @nosuspend function(v: any, base: number?): number?

Converts a value to a number, or nil when it has no numeric meaning. With base, v is read as an unsigned integer numeral in that base.

Arguments#

Returns#

tostringfunction#

local tostring: @nosuspend function(borrows v: any): string

Converts a value to a string, honoring a __tostring metamethod.

Arguments#

Returns#

typefunction#

local type: @nosuspend function(borrows v: any): ("nil"
| "boolean"
| "number"
| "string"
| "table"
| "function"
| "thread"
| "userdata"
| "cdata")

Returns the type name of a value: "nil", "boolean", "number", "string", "table", "function", "thread" or "userdata", plus "cdata" for FFI values.

The result is the closed set of those names rather than string, so a comparison against one of them narrows, a chain over all of them is exhaustive, and a comparison against a name LuaJIT never returns is caught where it is written.

Arguments#

Returns#

unpackfunction#

local unpack: function<T>(t: const{T}, i: number?, j: number?): ...T

Returns the elements of t from index i through j as separate values.

Type parameters#

Arguments#

Returns#

xpcallfunction#

local xpcall: function<E, A..., R...>(
    scoped f: function(A...): R...,
    scoped handler: function(any): E,
    A...
): ((true, R...) | (false, E))
    & function<E, A..., R...>(
        takes f: function(A...): R...,
        scoped handler: function(any): E,
        A...
    ): ((true, R...) | (false, E))

Like pcall, but runs handler on the error before the stack unwinds, so it can still collect a traceback.

Type parameters#

Arguments#

Returns#

argvariable#

local arg: {string}

The command-line arguments of the running script, where arg[1] is the first one. Index 0 holds the script name, and negative indices hold the interpreter and the options it was given.

string#

String manipulation and pattern matching. Every function here is also reachable as a method on a string value, so s:upper() means string.upper(s).

string.bytefunction#

local byte: @nosuspend function(s: string, i: number?, j: number?): ...integer

Returns the numeric codes of the characters of s from i to j.

Arguments#

Returns#

string.charfunction#

local char: @nosuspend function(...: number): string

Builds a string from the given character codes.

Arguments#

Returns#

string.dumpfunction#

local dump: @nosuspend function(f: any, strip: (boolean | string)?): string

Returns a binary representation of a Lua function that has no upvalues, in a form loadstring accepts.

LuaJIT also accepts a mode string in place of the boolean: s discards debug information as true does, and d writes the entries of a template table in sorted order rather than in the order its keys hash, which is what makes two dumps of a function compare equal across processes.

Arguments#

Returns#

string.findfunction#

local find: @nosuspend function<Pattern is string, Plain is boolean?>(
    s: string,
    pat: Pattern,
    init: number?,
    plain: Plain?
): unpackof __NuppFindResults(Pattern, Plain)

Finds the first match of pattern pat in s, at or after init. Any captures the pattern has follow the two returned indices.

Type parameters#

Arguments#

Returns#

string.formatfunction#

local format: @nosuspend function<Format is string>(
    fmt: Format,
    ...: unpackof __NuppFormatArguments(Format, nupp.Debug)
): string

Formats the arguments into fmt using LuaJIT's bounded-width printf subset, plus %q quoting, %p object identity, and hexadecimal floats with %a/%A.

Type parameters#

Arguments#

Returns#

string.gmatchfunction#

local gmatch: @nosuspend function<Pattern is string>(
    s: string,
    pat: Pattern
): function(): ((unpackof __NuppGmatchResults(Pattern)) | (nil))

Returns an iterator over each successive match of pat in s, or over that match's captures when the pattern has any. Anchors have no special meaning here.

run out

Type parameters#

Arguments#

Returns#

string.gsubfunction#

local gsub: @nosuspend function<Pattern is string>(
    s: string,
    pat: Pattern,
    repl: any,
    n: number?
): unpackof __NuppGsubResults(Pattern)

Replaces matches of pat in s. repl may be a string, in which %1 through %9 stand for captures and %0 for the whole match, a table looked up by the first capture, or a function called with the captures.

Type parameters#

Arguments#

Returns#

string.lenfunction#

local len: @nosuspend function(s: string): integer

Returns the length of s in bytes.

Arguments#

Returns#

string.lowerfunction#

local lower: @nosuspend function(s: string): string

Returns s with every ASCII letter folded to lower case.

Arguments#

Returns#

string.matchfunction#

local match: @nosuspend function<Pattern is string>(
    s: string,
    pat: Pattern,
    init: number?
): unpackof __NuppMatchResults(Pattern)

Returns the captures of the first match of pat in s, or the whole match when the pattern has no captures.

Type parameters#

Arguments#

Returns#

string.repfunction#

local rep: @nosuspend function(s: string, n: number, sep: string?): string

Returns n copies of s, with sep between consecutive copies.

Arguments#

Returns#

string.reversefunction#

local reverse: @nosuspend function(s: string): string

Returns the bytes of s in reverse order.

Arguments#

Returns#

string.subfunction#

local sub: @nosuspend function(s: string, i: number, j: number?): string

Returns the substring of s running from i through j.

Arguments#

Returns#

string.upperfunction#

local upper: @nosuspend function(s: string): string

Returns s with every ASCII letter folded to upper case.

Arguments#

Returns#

table#

Table manipulation. These functions work on the array part of a table: the integer keys 1 through #t.

table.clearfunction#

local clear: function(t: table)

@readonly

Removes every key from t while keeping the space it has already allocated, so it can be refilled without reallocating.

Arguments#

table.clonefunction#

local clone: @nosuspend function<T is table>(t: T): T

@readonly

Copies t one level deep: every key it holds directly, and its metatable, are carried over, while a value that is itself a table stays shared between the two. Neither __index nor __pairs is consulted, so what comes back is what next would have walked.

Type parameters#

Arguments#

Returns#

table.concatfunction#

local concat: @nosuspend function(t: table, sep: string?, i: number?, j: number?): string

Joins the elements t[i] through t[j], each of which must be a string or a number, into a single string.

Arguments#

Returns#

table.maxnfunction#

local maxn: @nosuspend function(t: table): number

Returns the largest positive numeric key of t, or 0 when it has none. Deprecated, and unlike #t it also sees keys past a hole.

Arguments#

Returns#

table.newfunction#

local new: function(narray: number, nhash: number): table

@readonly

Creates a table preallocated for narray array slots and nhash hash slots, so filling it in does not have to rehash.

Arguments#

Returns#

table.removefunction#

local remove: @nosuspend function(t: table, pos: number?): any

Removes the element at pos, shifting later elements down.

Arguments#

Returns#

table.sortfunction#

local sort: function<V>(t: {V}, scoped cmp: (function(V, V): boolean)?)

Sorts t in place, between indices 1 and #t. The sort is not stable, and cmp must be a strict order or it may raise.

Type parameters#

Arguments#

table.insertvariable#

local insert: (@nosuspend function<V>(t: {V}, value: V): nil)
& (@nosuspend function<V>(t: {V}, pos: integer, value: V): nil)

Inserts value at position pos, shifting later elements up. Called with two arguments, appends that value to the end instead.

math#

Mathematical functions and constants, operating on the doubles that plain Lua numbers are.

math.absfunction#

local abs: @nosuspend function(x: number): number

Returns the absolute value of x.

Arguments#

Returns#

math.acosfunction#

local acos: @nosuspend function(x: number): number

Returns the arc cosine of x, in radians.

Arguments#

Returns#

math.asinfunction#

local asin: @nosuspend function(x: number): number

Returns the arc sine of x, in radians.

Arguments#

Returns#

math.atanfunction#

local atan: @nosuspend function(x: number): number

Returns the arc tangent of x, in radians.

Arguments#

Returns#

math.atan2function#

local atan2: @nosuspend function(y: number, x: number): number

Returns the arc tangent of y / x, using the sign of both arguments to place the result in the right quadrant.

Arguments#

Returns#

math.ceilfunction#

local ceil: @nosuspend function(x: number): integer

Returns the smallest integer that is not less than x. NaN and the infinities pass through unchanged, so the result is a whole number only when x is finite.

Arguments#

Returns#

math.cosfunction#

local cos: @nosuspend function(x: number): number

Returns the cosine of x, which is in radians.

Arguments#

Returns#

math.coshfunction#

local cosh: @nosuspend function(x: number): number

Returns the hyperbolic cosine of x.

Arguments#

Returns#

math.degfunction#

local deg: @nosuspend function(r: number): number

Converts the angle r from radians to degrees.

Arguments#

Returns#

math.expfunction#

local exp: @nosuspend function(x: number): number

Returns e raised to the power x.

Arguments#

Returns#

math.floorfunction#

local floor: @nosuspend function(x: number): integer

Returns the largest integer that is not greater than x. NaN and the infinities pass through unchanged, so the result is a whole number only when x is finite.

Arguments#

Returns#

math.fmodfunction#

local fmod: @nosuspend function(x: number, y: number): number

Returns the remainder of x / y, keeping the sign of x.

Arguments#

Returns#

math.frexpfunction#

local frexp: @nosuspend function(x: number): (number, number)

Splits x into a fraction in [0.5,1) and an exponent, such that x equals the fraction times 2 raised to the exponent.

Arguments#

Returns#

math.ldexpfunction#

local ldexp: @nosuspend function(m: number, e: number): number

Returns m times 2 raised to the power e.

Arguments#

Returns#

math.logfunction#

local log: @nosuspend function(x: number, base: number?): number

Returns the natural logarithm of x, or its logarithm in base.

Arguments#

Returns#

math.maxfunction#

local max: function<N is number>(...: N): N

Returns the largest of its arguments. Comparing integers gives an integer back, so a bound taken this way stays usable as an index.

Type parameters#

Arguments#

Returns#

math.minfunction#

local min: function<N is number>(...: N): N

Returns the smallest of its arguments. Comparing integers gives an integer back, so a bound taken this way stays usable as an index.

Type parameters#

Arguments#

Returns#

math.modffunction#

local modf: @nosuspend function(x: number): (number, number)

Splits x into its integral and fractional parts, both keeping the sign of x.

Arguments#

Returns#

math.powfunction#

local pow: @nosuspend function(x: number, y: number): number

Returns x raised to the power y, the same as x ^ y.

Arguments#

Returns#

math.radfunction#

local rad: @nosuspend function(d: number): number

Converts the angle d from degrees to radians.

Arguments#

Returns#

math.randomfunction#

local random: @nosuspend function(): number & function(m: number): number & function(m: number, n: number): number

Returns a pseudo-random number: a float in [0,1) with no arguments, a bounded number with one, or a number between m and n with two.

Arguments#

Returns#

math.randomseedfunction#

local randomseed: @nosuspend function(seed: number)

Seeds the pseudo-random generator, which starts from a fixed state.

Arguments#

math.sinfunction#

local sin: @nosuspend function(x: number): number

Returns the sine of x, which is in radians.

Arguments#

Returns#

math.sinhfunction#

local sinh: @nosuspend function(x: number): number

Returns the hyperbolic sine of x.

Arguments#

Returns#

math.sqrtfunction#

local sqrt: @nosuspend function(x: number): number

Returns the square root of x.

Arguments#

Returns#

math.tanfunction#

local tan: @nosuspend function(x: number): number

Returns the tangent of x, which is in radians.

Arguments#

Returns#

math.tanhfunction#

local tanh: @nosuspend function(x: number): number

Returns the hyperbolic tangent of x.

Arguments#

Returns#

math.hugevariable#

local huge: number

Positive infinity, which compares greater than any other number.

math.pivariable#

local pi: number

The ratio of a circle's circumference to its diameter.

os#

Operating-system facilities: clocks and calendars, the environment, processes and file names.

os.clockfunction#

local clock: function(): number

Returns the CPU time the program has used, in seconds. It measures intervals of work, not wall-clock time.

Returns#

os.datefunction#

local date: function<Format is string>(fmt: Format?, t: number?): __NuppDateResult(Format, DateFields)

Formats the time t as text according to fmt. A leading "!" formats in UTC rather than local time, and a fmt of "*t" returns a table of date fields instead of a string.

A literal fmt decides which of those two the call returns: "t" and "!t" give DateFields, and every other literal gives a string. A fmt the compiler cannot read gives either, so narrow it before use.

Type parameters#

Arguments#

Returns#

os.difftimefunction#

local difftime: function(t2: number, t1: number): number

Returns the number of seconds from t1 to t2.

Arguments#

Returns#

os.executefunction#

local execute: function(cmd: string?): any

Runs cmd with the system shell and waits for it. With no argument it instead reports whether a shell is available at all.

Arguments#

Returns#

os.exitfunction#

local exit: function(code: any?): never

Ends the process, closing the interpreter state on the way out.

Arguments#

Returns#

os.getenvfunction#

local getenv: function(name: string): string?

Returns the value of the environment variable name.

Arguments#

Returns#

os.removefunction#

local remove: function(path: string): (boolean?, string?)

Deletes the file, or the empty directory, at path.

Arguments#

Returns#

os.renamefunction#

local rename: function(from: string, to: string): (boolean?, string?)

Renames the file or directory at from to to.

Arguments#

Returns#

os.timefunction#

local time: function(spec: table?): number

Returns the current time, or the time that spec describes.

Arguments#

Returns#

os.tmpnamefunction#

local tmpname: function(): string

Returns a file name usable for a temporary file. The file itself is neither created nor removed for you.

Returns#

package#

package.loadlibfunction#

local loadlib: function(path: string, symbol: string): (any, string?)

Opens a shared object and returns the named C entry point, or nil and why when it could not be opened.

Arguments#

Returns#

package.configvariable#

local config: string

Platform path separators and template markers.

package.cpathvariable#

local cpath: string

Search templates used by require for C modules.

package.loadedvariable#

local loaded: {[string]: any}

Every module require has already returned, by the name it was asked for. Writing an entry makes that name resolve without a search.

package.loadersvariable#

local loaders: {function(string): any}

Lua 5.1 and Lua 5.2 names for the module-loader chain.

package.pathvariable#

local path: string

Search templates used by require for Lua modules.

package.preloadvariable#

local preload: {[string]: function(...: any): any}

Modules made available without consulting the filesystem.

package.searchersvariable#

local searchers: {function(string): any}?

io#

io.closefunction#

local close: function(f: LuaFile?): boolean?

Closes f, or the default output file when it is omitted.

Arguments#

Returns#

io.inputfunction#

local input: function(f: (LuaFile | string)?): LuaFile

Sets the default input file, opening f first when it is a name. With no argument it returns the current one instead.

Arguments#

Returns#

io.linesfunction#

local lines: function(path: string?): @nosuspend function(): string?

Returns an iterator over the lines of the file at path, closing it once the iterator runs out, or over the default input file when path is omitted.

Arguments#

Returns#

io.openfunction#

local open: function(path: string, mode: string?): (affine(LuaFile, _)?, string?)

Opens the file at path. Modes are "r", "w" and "a", with "+" added for update and a trailing "b" for binary.

Arguments#

Returns#

io.outputfunction#

local output: function(f: (LuaFile | string)?): LuaFile

Sets the default output file, opening f first when it is a name. With no argument it returns the current one instead.

Arguments#

Returns#

io.popenfunction#

local popen: function(cmd: string, mode: string?): (affine(LuaFile, _)?, string?)

Runs cmd in a separate process and returns a handle on one of its streams: its standard output for "r", its standard input for "w".

Arguments#

Returns#

io.readfunction#

local read: function(...: any): any

Reads the default input file according to the given formats: "l" for a line, "n" for a number, "*a" for the rest, or a byte count.

Arguments#

Returns#

io.tmpfilefunction#

local tmpfile: function(): affine(LuaFile, _)?

Opens a temporary file in update mode, removed when the program ends.

Returns#

io.writefunction#

local write: function(...: any): any

Writes each argument, which must be a string or a number, to the default output file.

Arguments#

Returns#

io.stderrvariable#

local stderr: LuaFile

The standard error stream.

io.stdinvariable#

local stdin: LuaFile

The standard input stream.

io.stdoutvariable#

local stdout: LuaFile

The standard output stream.

io.typevariable#

local type: @nosuspend function(value: any): ("file" | "closed file")?

Classifies an open or closed file handle.

coroutine#

coroutine.createfunction#

local create: function(f: any): thread

Creates a coroutine with f as its body. The body does not start running until the first resume.

Arguments#

Returns#

coroutine.isyieldablefunction#

local isyieldable: function(): boolean

Whether the running coroutine is allowed to yield, which is false on the main coroutine.

Returns#

coroutine.resumefunction#

local resume: function<A...>(co: thread, A...): ...any

Starts or continues co. The extra arguments go to its body on the first call, and become the results of the yield that suspended it on later ones.

Type parameters#

Arguments#

Returns#

coroutine.runningfunction#

local running: function(): (thread?, boolean)

Returns the coroutine that is running.

Returns#

coroutine.statusfunction#

local status: function(co: thread): string

Returns the state of co: "running", "suspended", "normal" for one that resumed another coroutine, or "dead".

Arguments#

Returns#

coroutine.wrapfunction#

local wrap: function(f: any): any

Creates a coroutine and returns a function that resumes it, passing along its own arguments. Errors propagate to the caller instead of being returned as a status.

Arguments#

Returns#

coroutine.yieldfunction#

local yield: function<Y...>(Y...): ...any

Suspends the running coroutine. The arguments become the results of the resume that started it.

Type parameters#

Arguments#

Returns#

bit#

Nupp provides access to LuaJIT's BitOp library, which every target has.

const bit = require("bit")

-- No operator spells these, so the module does.
print(bit.tohex(bit.bswap(0x11223344))) -- 44332211
print(bit.rol(0xFF, 8))                 -- 65280

-- These have one, so write the operator and let it lower per target.
print(0xF0 & 0x3C)                      -- 48

bit.arshiftfunction#

local arshift: @nosuspend function(x: number, n: number): integer

Shifts x right by n bits, copying the sign bit down.

Arguments#

Returns#

bit.bandfunction#

local band: @nosuspend function(x: number, ...: number): integer

Returns the bitwise and of x and every remaining argument.

Arguments#

Returns#

bit.bnotfunction#

local bnot: @nosuspend function(x: number): integer

Returns the bitwise complement of x.

Arguments#

Returns#

bit.borfunction#

local bor: @nosuspend function(x: number, ...: number): integer

Returns the bitwise or of x and every remaining argument.

Arguments#

Returns#

bit.bswapfunction#

local bswap: @nosuspend function(x: number): integer

Swaps the byte order of x, converting between endiannesses.

Arguments#

Returns#

bit.bxorfunction#

local bxor: @nosuspend function(x: number, ...: number): integer

Returns the bitwise exclusive or of x and every remaining argument.

Arguments#

Returns#

bit.lshiftfunction#

local lshift: @nosuspend function(x: number, n: number): integer

Shifts x left by n bits, filling with zeros.

Arguments#

Returns#

bit.rolfunction#

local rol: @nosuspend function(x: number, n: number): integer

Rotates x left by n bits.

Arguments#

Returns#

bit.rorfunction#

local ror: @nosuspend function(x: number, n: number): integer

Rotates x right by n bits.

Arguments#

Returns#

bit.rshiftfunction#

local rshift: @nosuspend function(x: number, n: number): integer

Shifts x right by n bits without sign extension.

Arguments#

Returns#

bit.tobitfunction#

local tobit: @nosuspend function(x: number): integer

Normalizes x into the signed 32-bit integer range, wrapping around.

Arguments#

Returns#

bit.tohexfunction#

local tohex: @nosuspend function(x: number, n: number?): string

Returns x in hexadecimal, using n digits.

Arguments#

Returns#

jit#

jit.attachfunction#

local attach: function(callback: function(...: any), event: string?)

Adds or removes a handler for a compiler event, so a program can watch the JIT as it works. Omitting event removes the handler.

The handler's own signature is decided by the event, which is why this one is variadic:

• "bc": (func), once per function the VM records bytecode for. * "trace": (what, tr, func, pc, otr, oex), where what is "start", "stop", "abort", "flush" or "free". On "abort", otr is an error code to look up in require("jit.vmdef").traceerr and oex is its argument; on "start" for a side trace they are the parent trace and its exit.
• "record": (tr, func, pc, depth), per bytecode recorded. * "texit": (tr, ex, ngpr, nfpr), per trace exit.

A handler runs inside the compiler, so it must not allocate heavily, raise, or re-enter the VM in ways that would trigger further compilation. Dropping the last reference to a handler does not detach it: hold onto it and pass it back with no event to remove it.

Arguments#

jit.flushfunction#

local flush: function(f: any?, recursive: boolean?)

Flushes compiled code, for f or for the whole cache when it is omitted, so the affected code is traced again from scratch. A trace number flushes that one trace.

Arguments#

jit.offfunction#

local off: function(f: any?, recursive: boolean?)