2.16. Built-in Functions

2.16.1. Global Symbols

array(size[, fill])

creates and returns array of a specified size. If the optional parameter fill is specified its value will be used to fill the new array’s slots. If the fill parameter is omitted, null is used instead.

seterrorhandler(func)

sets the runtime error handler

callee()

returns the currently running closure

setdebughook(hook_func)

sets the debug hook

enabledebuginfo(enable)

enable/disable the debug line information generation at compile time. enable != null enables. enable == null disables.

getroottable()

returns the root table of the VM.

setroottable(table)

sets the root table of the VM. And returns the previous root table.

getconsttable()

returns the const table of the VM.

setconsttable(table)

sets the const table of the VM; returns the previous const table.

assert(exp[, message])

throws an exception if exp is null or false. Throws “assertion failed” string by default, or message if specified.

print(x)

prints x to the standard output

error(x)

prints x in the standard error output

compilestring(string[, buffername])

compiles a string containing a squirrel script into a function and returns it:

local compiledscript=compilestring("::print(\"ciao\")");
//run the script
compiledscript();
collectgarbage()

Runs the garbage collector and returns the number of reference cycles found (and deleted). This function only works on garbage collector builds.

resurrectunreachable()

Runs the garbage collector and returns an array containing all unreachable object found. If no unreachable object is found, null is returned instead. This function is meant to help debugging reference cycles. This function only works on garbage collector builds.

type(obj)

return the ‘raw’ type of an object without invoking the metamethod ‘_typeof’.

getstackinfos(level)

returns the stack informations of a given call stack level. returns a table formatted as follow:

{
    func="DoStuff", //function name

    src="test.nut", //source file

    line=10,        //line number

    locals = {      //a table containing the local variables

        a=10,

        testy="I'm a string"
    }
}

level = 0 is getstackinfos() itself! level = 1 is the current function, level = 2 is the caller of the current function, and so on. If the stack level doesn’t exist the function returns null.

newthread(threadfunc)

creates a new cooperative thread object(coroutine) and returns it

_versionnumber_

integer values describing the version of VM and compiler. e.g. for Squirrel 3.0.1 this value will be 301

_version_

string values describing the version of VM and compiler.

_charsize_

size in bytes of the internal VM representation for characters(1 for ASCII builds 2 for UNICODE builds).

_intsize_

size in bytes of the internal VM representation for integers(4 for 32bits builds 8 for 64bits builds).

_floatsize_

size in bytes of the internal VM representation for floats(4 for single precision builds 8 for double precision builds).

2.16.1.1. Default delegates

Except null and userdata every squirrel object has a default delegate containing a set of functions to manipulate and retrieve information from the object itself.

2.16.2. Integer

integer.tofloat()

convert the number to float and returns it

integer.tostring()

converts the number to string and returns it

integer.tointeger()

dummy function; returns the value of the integer.

integer.tochar()

returns a string containing a single character represented by the integer.

integer.weakref()

dummy function; returns the integer itself.

2.16.3. Float

float.tofloat()

returns the value of the float(dummy function)

float.tointeger()

converts the number to integer and returns it

float.tostring()

converts the number to string and returns it

float.tochar()

returns a string containing a single character represented by the integer part of the float.

float.weakref()

dummy function; returns the float itself.

2.16.4. Bool

bool.tofloat()

returns 1.0 for true 0.0 for false

bool.tointeger()

returns 1 for true 0 for false

bool.tostring()

returns “true” for true and “false” for false

bool.weakref()

dummy function; returns the bool itself.

2.16.5. String

string.len()

returns the string length

string.tointeger([base])

Converts the string to integer and returns it. An optional parameter base can be specified–if a base is not specified, it defaults to base 10.

string.tofloat()

converts the string to float and returns it

string.tostring()

returns the string (really, a dummy function)

string.slice(start[, end])

returns a section of the string as new string. Copies from start to the end (not included). If start is negative the index is calculated as length + start, if end is negative the index is calculated as length + end. If end is omitted end is equal to the string length.

string.find(substr[, startidx])

Searches a sub string (substr) starting from the index startidx and returns the index of its first occurrence. If startidx is omitted the search operation starts from the beginning of the string. The function returns null if substr is not found.

string.tolower()

returns a lowercase copy of the string.

string.toupper()

returns a uppercase copy of the string.

string.weakref()

returns a weak reference to the object.

2.16.6. Table

table.len()

returns the number of slots contained in a table

table.rawget(key)

tries to get a value from the slot ‘key’ without employing delegation

table.rawset(key, val)

Sets the slot ‘key’ with the value ‘val’ without employing delegation. If the slot does not exists, it will be created. Returns table itself.

table.rawdelete()

Deletes the slot key without employing delegation and returns its value. If the slot does not exists, returns null.

table.rawin(key)

returns true if the slot ‘key’ exists. the function has the same effect as the operator ‘in’ but does not employ delegation.

table.weakref()

returns a weak reference to the object.

table.tostring()

Tries to invoke the _tostring metamethod. If that fails, it returns “(table : pointer)”.

table.clear()

removes all the slots from the table. Returns table itself.

table.setdelegate(table)

Sets the delegate of the table. To remove a delegate, ‘null’ must be passed to the function. The function returns the table itself (e.g. a.setdelegate(b) – in this case ‘a’ is the return value).

table.getdelegate()

returns the table’s delegate or null if no delegate was set.

table.filter(func(key, val))

Creates a new table with all values that pass the test implemented by the provided function. In detail, it creates a new table, invokes the specified function for each key-value pair in the original table; if the function returns ‘true’, then the value is added to the newly created table at the same key.

table.keys()

returns an array containing all the keys of the table slots.

table.values()

returns an array containing all the values of the table slots.

2.16.7. Array

array.len()

returns the length of the array

array.append(val)

appends the value ‘val’ at the end of the array. Returns array itself.

array.push(val)

appends the value ‘val’ at the end of the array. Returns array itself.

array.extend(array)

Extends the array by appending all the items in the given array. Returns array itself.

array.pop()

removes a value from the back of the array and returns it.

array.top()

returns the value of the array with the higher index

array.insert(idx, val)

inserts the value ‘val’ at the position ‘idx’ in the array. Returns array itself.

array.remove(idx)

removes the value at the position ‘idx’ in the array and returns its value.

array.resize(size[, fill])

Resizes the array. If the optional parameter ‘fill’ is specified, its value will be used to fill the new array’s slots when the size specified is bigger than the previous size. If the fill parameter is omitted, null is used instead. Returns array itself.

array.sort([compare_func])

Sorts the array in-place. A custom compare function can be optionally passed. The function prototype as to be the following.:

function custom_compare(a,b)
{
    if(a>b) return 1
    else if(a<b) return -1
    return 0;
}

a more compact version of a custom compare can be written using a lambda expression and the operator <=>

arr.sort(@(a,b) a <=> b);

Returns array itself.

array.reverse()

reverse the elements of the array in place. Returns array itself.

array.slice(start[, end])

Returns a section of the array as new array. Copies from start to the end (not included). If start is negative the index is calculated as length + start, if end is negative the index is calculated as length + end. If end is omitted end is equal to the array length.

array.weakref()

returns a weak reference to the object.

array.tostring()

returns the string “(array : pointer)”.

array.clear()

removes all the items from the array

array.map(func(item_value, [item_index], [array_ref]))

Creates a new array of the same size. For each element in the original array invokes the function ‘func’ and assigns the return value of the function to the corresponding element of the newly created array. Provided func can accept up to 3 arguments: array item value (required), array item index (optional), reference to array itself (optional).

array.apply(func([item_value, [item_index], [array_ref]))

for each element in the array invokes the function ‘func’ and replace the original value of the element with the return value of the function.

array.reduce(func(prevval, curval)[, initializer])

Reduces an array to a single value. For each element in the array invokes the function ‘func’ passing the initial value (or value from the previous callback call) and the value of the current element. The return value of the function is then used as ‘prevval’ for the next element. If the optional initializer is present, it is placed before the items of the array in the calculation, and serves as a default when the sequence is empty. If initializer is not given then for sequence contains only one item, reduce() returns the first item, and for empty sequence returns null.

Given an sequence with 2 or more elements (including initializer) calls the function with the first two elements as the parameters, gets that result, then calls the function with that result and the third element, gets that result, calls the function with that result and the fourth parameter and so on until all element have been processed. Finally, returns the return value of the last invocation of func.

array.filter(func(index, val))

Creates a new array with all elements that pass the test implemented by the provided function. In detail, it creates a new array, for each element in the original array invokes the specified function passing the index of the element and it’s value; if the function returns ‘true’, then the value of the corresponding element is added on the newly created array.

array.find(value)

Performs a linear search for the value in the array. Returns the index of the value if it was found null otherwise.

2.16.8. Function

function.call(_this, args...)

calls the function with the specified environment object(‘this’) and parameters

function.pcall(_this, args...)

calls the function with the specified environment object(‘this’) and parameters, this function will not invoke the error callback in case of failure(pcall stays for ‘protected call’)

function.acall(array_args)

calls the function with the specified environment object(‘this’) and parameters. The function accepts an array containing the parameters that will be passed to the called function.Where array_args has to contain the required ‘this’ object at the [0] position.

function.pacall(array_args)

calls the function with the specified environment object(‘this’) and parameters. The function accepts an array containing the parameters that will be passed to the called function.Where array_args has to contain the required ‘this’ object at the [0] position. This function will not invoke the error callback in case of failure(pacall stays for ‘protected array call’)

function.weakref()

returns a weak reference to the object.

function.tostring()

returns the string “(closure : pointer)”.

function.setroot(table)

sets the root table of a closure

function.getroot()

returns the root table of the closure

function.bindenv(env)

clones the function(aka closure) and bind the environment object to it(table,class or instance). the this parameter of the newly create function will always be set to env. Note that the created function holds a weak reference to its environment object so cannot be used to control its lifetime.

function.getinfos()

returns a table containing informations about the function, like parameters, name and source name;

//the data is returned as a table is in form
//pure squirrel function
{
  native = false
  name = "zefuncname"
  src = "/somthing/something.nut"
  parameters = ["a","b","c"]
  defparams = [1,"def"]
  varargs = 2
}
//native C function
{
  native = true
  name = "zefuncname"
  paramscheck = 2
  typecheck = [83886082,83886384] //this is the typemask (see C defines OT_INTEGER,OT_FLOAT etc...)
}

2.16.9. Class

class.instance()

returns a new instance of the class. this function does not invoke the instance constructor. The constructor must be explicitly called (eg. class_inst.constructor(class_inst) ).

class.getattributes(membername)

returns the attributes of the specified member. if the parameter member is null the function returns the class level attributes.

class.setattributes(membername, attr)

sets the attribute of the specified member and returns the previous attribute value. if the parameter member is null the function sets the class level attributes.

class.rawin(key)

returns true if the slot ‘key’ exists. the function has the same effect as the operator ‘in’ but does not employ delegation.

class.weakref()

returns a weak reference to the object.

class.tostring()

returns the string “(class : pointer)”.

class.rawget(key)

tries to get a value from the slot ‘key’ without employing delegation

class.rawset(key, val)

sets the slot ‘key’ with the value ‘val’ without employing delegation. If the slot does not exists, it will be created.

class.newmember(key, val[, attrs][, bstatic])

sets/adds the slot ‘key’ with the value ‘val’ and attributes ‘attrs’ and if present invokes the _newmember metamethod. If bstatic is true the slot will be added as static. If the slot does not exists , it will be created.

class.rawnewmember(key, val[, attrs][, bstatic])

sets/adds the slot ‘key’ with the value ‘val’ and attributes ‘attrs’. If bstatic is true the slot will be added as static. If the slot does not exist, it will be created. It doesn’t invoke any metamethod.

2.16.10. Class Instance

instance.getclass()

returns the class that created the instance.

instance.rawin(key)
Arguments:
  • key – ze key

returns true if the slot ‘key’ exists. the function has the same effect as the operator ‘in’ but does not employ delegation.

instance.weakref()

returns a weak reference to the object.

instance.tostring()

tries to invoke the _tostring metamethod, if failed. returns “(instance : pointer)”.

instance.rawget(key)

tries to get a value from the slot ‘key’ without employing delegation

instance.rawset(key, val)

sets the slot ‘key’ with the value ‘val’ without employing delegation. If the slot does not exists, it will be created.

2.16.11. Generator

generator.getstatus()

returns the status of the generator as string : “running”, “dead” or “suspended”.

generator.weakref()

returns a weak reference to the object.

generator.tostring()

returns the string “(generator : pointer)”.

2.16.12. Thread

thread.call(...)

starts the thread with the specified parameters

thread.wakeup([wakeupval])

wakes up a suspended thread, accepts a optional parameter that will be used as return value for the function that suspended the thread(usually suspend())

thread.wakeupthrow(objtothrow[, propagateerror = true])

wakes up a suspended thread, throwing an exception in the awaken thread, throwing the object ‘objtothrow’.

thread.getstatus()

returns the status of the thread (“idle”,”running”,”suspended”)

thread.weakref()

returns a weak reference to the object.

thread.tostring()

returns the string “(thread : pointer)”.

thread.getstackinfos(stacklevel)

returns the stack frame informations at the given stack level (0 is the current function 1 is the caller and so on).

2.16.13. Weak Reference

weakreference.ref()

returns the object that the weak reference is pointing at; null if the object that was point at was destroyed.

weakreference.weakref()

returns a weak reference to the object.

weakreference.tostring()

returns the string “(weakref : pointer)”.