Lua Global

The following is a list of functions and variables that are native to Lua 5.1.

Functions

boolean rawequal(table v1, table v2)

ReturnsTrue if v1 equals v2, or false otherwise.

Checks whether v1 is equal to v2, without invoking any metamethod. Returns a boolean.

• v1 The first argument.
• v2 The second argument.

string type(table o)

ReturnsOne of "nil", "number", "string", "boolean", "table", "function", "thread", "userdata".

Returns the type of its only argument, coded as a string. The possible results of this function are "nil" (a string, not the value nil), "number", "string", "boolean", "table", "function", "thread", and "userdata".

• o The argument.

print(type("hello"))  -- string
print(type(nil))      -- nil
print(type(1))        -- number
print(type(true))     -- boolean
print(type(function()end)) -- function
print(type(YaGame))   -- userdata

The data returned by APIs is usually a userdata.

string tostring(table o)

ReturnsThe string value.

Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format. If the metatable of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result.

• o The only argument.

local f = float3.New(1,2,3)
print(tostring(f))  -- [1,2,3]

float3 implements __tostring in its metatable, and float3 can be converted to a string in the format [x,y,z].

number tonumber(string o)

Tries to convert a string to a number, if success returns a number or nil otherwise.

• o The string to be converted to a number.

print(tonumber("hello"))      -- nil
print(tonumber("1234hello"))  -- nil
print(tonumber("1234"))       -- 1234

number tonumber(number o)

ReturnsThe argument.

Returns the the argument self.

• o The argument.

table assert(... arguments)

ReturnsThe arguments passed to this function if the first argument is not false nor nil.

Checks whether the first argument is not false or nil. Returns arguments as is if the first argument is not false nor nil, or raises an error.

• arguments Arguments to check.

local function div(a, b)
    assert(b ~= 0, "cannot divided by zero")
    return a / b
end
print(div(10, 2))  -- output: 5
print(div(10, 0))  -- raise an error

In this example, the div function takes two arguments and returns their quotient, which contains an assert statement to ensure the second argument is not zero. If the assertion fails, the program execution will be stopped with an error raised.

void error(table msg)

Raises an error with a specific message (a string is preferred) and never returns. Terminates the last protected function (such as pcall) called and returns message as the error message.

• msg The error message.

function wont_print(o)
    error("terminate", 0)
    print(o)  -- never execute
end
local ok, errmsg = pcall(wont_print, 10)
print(ok, errmsg)                          -- output: false    terminate

In this example, the error statement in the wont_print function will raise an error with a message "terminated" and the following print statement will never execute because function error never returns.

boolean pcall(function func, ... arguments)

Returnsboolean, other return values

Calls the function in a protected mode. This means that any error inside func is not propagated; instead, pcall catches the error and returns the error message. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case, pcall also returns all results from the call, after this first result. In case of any error, pcall returns false plus the error message.

• func The function to call.
• arguments The arguments to pass.

local function div(a, b)
    if b == 0 then
        error("cannot divided by zero", 0)
    end
    return a / b
end
print(pcall(div, 10, 2))        -- output: true    5
print(pcall(div, 10, 0))        -- output: false   cannot divided by zero

In this example, we define a div function that throws an error if the second argument is zero. In the first print statement, pcall returns true with the quotient. In the second print statement, div function raises an error since the second argument b is zero, then pcall catches this error and returns false with an error message.

boolean xpcall(function func, function err)

Returnsboolean, other return values

This function is similar to pcall, except that you can set a new error handler. xpcall calls function func in protected mode, using err as the error handler. Any error inside func is not propagated; instead, xpcall catches the error, calls the err function with the original error object, and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In this case, xpcall also returns all results from the call, after this first result. In case of any error, xpcall returns false plus the result from err.

• func The function called in protected mode.
• err The error handler.

local function raise_error()
    error("an error", 0)
end
local function error_handler(err)
    return err .. " caught"
end
print(xpcall(raise_error, error_handler))       -- output: false   an error caught

table next(table table, table index)

ReturnsThe next index and element of the table.

Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. next returns the next index of the table and its associated value. When called with nil as its second argument, next returns an initial index and its associated value. When called with the last index, or with nil in an empty table, next returns nil. If the second argument is absent, then it is interpreted as nil. In particular, you can use next(t) to check whether a table is empty. The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numeric order, use a numerical for or the ipairs function.) The behavior of next is undefined if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may clear existing fields.

• table The table to traverse.
• index An index of the table.

-- Create a table with some key-value pairs
local t = { a=1, b=2, c=3 }
local k, v = next(t, nil)
while k ~= nil do
    print(k, v)
    k, v = next(t, k)
end
-- outputs: (the order may differ)
-- a 1
-- c 3
-- b 2

table ipairs(table table)

Returnsfunction, object, number

Returns three values: an iterator function, the table t, and 0, so that the construction

for i,v in ipairs(t) do body end

will iterate over the pairs (1,t[1]), (2,t[2]), ···, up to the first integer key absent from the table.

• table The table to iterate.

local t = {"a", "8", "*"}
for i, v in ipairs(t) do
    print(i, v)
end
-- outputs:
-- 1 a
-- 2 8
-- 3 *

In this example, ipairs is used in the for loop to iterate over the table t from the index 1 to the index 3. The loop variable i holds the value of the current index, and v holds the value of the current element.

table pairs(table table)

Returnsfunction, object, object

Returns three values: the next function, the table t, and nil, so that the construction

for k,v in pairs(t) do body end

will iterate over all key–value pairs of table t. See function next for the caveats of modifying the table during its traversal.

• table The table to iterate.

local t = { a=1, b=2, c=3 }
for k, v in pairs(t) do
    print(k, v)
end
-- outputs: (the order may differ)
-- a 1
-- c 3
-- b 2

In this example, pairs is used in the for loop to iterate over the table t in any order. The loop variable k holds the value of the current index, and v holds the value of the current element.

table rawget(table table, table index)

ReturnsThe value of table[index].

Gets the real value of table[index], without invoking any metamethod. table must be a table; index may be any value except nil.

• table A table.
• index Any value.

void rawset(table table, table index, table value)

Sets the real value of table[index] to value, without invoking any metamethod. table must be a table, index any value different from nil, and value any Lua value.

• table A table.
• index Any value.
• value Any value.

table unpack(... list)

ReturnsThe elements.

Flattens down the table as multiple return values. Returns the elements from the given table. This function is equivalent to

return list[i], list[i+1], ···, list[j]

• list The table to unpack.

local t = {1, 2, 3}
local x,y,z = unpack(t)
print(x, y, z)    -- output: 1   2   3

table select(number index, ... arguments)

ReturnsArguments after index.

Returns the all arguments beginning at number index.

• index The index of the first argument to return.
• arguments Some values.

print(select(2, 1, 2, 3, 4))        -- output: 2   3   4
print(select(2, 1, 2, 3, 4), "#")   -- output: 2   #

In the second print statement, the "#" argument following the select call removes all return values except the first of the select call, and only 2 and "#" self are printed.

number select(string index, ... arguments)

ReturnsThe count of arguments.

Returns the count of arguments.

• index The string "#".
• arguments Some values.

print(select("#", 1, 2, 3, 4))        -- output: 4

void print(... arguments)

Receives any number of arguments, and prints their values to the output. This can be used to log game information.

• arguments Some values.

print("hello", 1, 2, 3)  -- output: hello   1   2   3