3.4. Object creation and handling

SQRESULT sq_bindenv(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target closure

Returns

a SQRESULT

Remarks

the cloned closure holds the environment object as weak reference

pops an object from the stack (must be a table, instance, or class); clones the closure at position idx in the stack and sets the popped object as environment of the cloned closure. Then pushes the new cloned closure on top of the stack.

SQRESULT sq_createinstance(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target class

Returns

a SQRESULT

Remarks

the function doesn’t invoke the instance contructor. To create an instance and automatically invoke its contructor, sq_call must be used instead.

creates an instance of the class at ‘idx’ position in the stack. The new class instance is pushed on top of the stack.

SQRESULT sq_getbool(HSQUIRRELVM v, SQInteger idx, SQBool *b)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• b (SQBool*) – A pointer to the bool that will store the value

Returns

a SQRESULT

gets the value of the bool at the idx position in the stack.

SQRESULT sq_getbyhandle(HSQUIRRELVM v, SQInteger idx, HSQMEMBERHANDLE *handle)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack pointing to the class or instance

• handle (HSQMEMBERHANDLE*) – a pointer to the member handle

Returns

a SQRESULT

pushes the value of a class or instance member using a member handle (see sq_getmemberhandle)

SQRESULT sq_getclosureinfo(HSQUIRRELVM v, SQInteger idx, SQInteger *nparams, SQInteger *nfreevars)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target closure

• nparams (SQInteger*) – a pointer to an integer that will store the number of parameters

• nfreevars (SQInteger*) – a pointer to an integer that will store the number of free variables

Returns

an SQRESULT

retrieves number of parameters and number of freevariables from a quirrel closure.

SQRESULT sq_getclosurename(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target closure

Returns

an SQRESULT

pushes the name of the closure at position idx in the stack. Note that the name can be a string or null if the closure is anonymous or a native closure with no name assigned to it.

SQRESULT sq_getclosureroot(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target closure

Returns

an SQRESULT

pushes the root table of the closure at position idx in the stack

SQRESULT sq_getfloat(HSQUIRRELVM v, SQInteger idx, SQFloat *f)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• f (SQFloat*) – A pointer to the float that will store the value

Returns

a SQRESULT

gets the value of the float at the idx position in the stack.

SQHash sq_gethash(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

Returns

the hash key of the value at the position idx in the stack

Remarks

the hash value function is the same used by the VM.

returns the hash key of a value at the idx position in the stack.

SQRESULT sq_getinstanceup(HSQUIRRELVM v, SQInteger idx, SQUserPointer *up, SQUSerPointer typetag)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• up (SQUserPointer*) – a pointer to the userpointer that will store the result

• typetag (SQUSerPointer) – the typetag that has to be checked, if this value is set to 0 the typetag is ignored.

Returns

a SQRESULT

gets the userpointer of the class instance at position idx in the stack. if the parameter ‘typetag’ is different than 0, the function checks that the class or a base class of the instance is tagged with the specified tag; if not the function fails. If ‘typetag’ is 0 the function will ignore the tag check.

SQRESULT sq_getinteger(HSQUIRRELVM v, SQInteger idx, SQInteger *i)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• i (SQInteger*) – A pointer to the integer that will store the value

Returns

a SQRESULT

gets the value of the integer at the idx position in the stack.

SQRESULT sq_getmemberhandle(HSQUIRRELVM v, SQInteger idx, HSQMEMBERHANDLE *handle)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack pointing to the class

• handle (HSQMEMBERHANDLE*) – a pointer to the variable that will store the handle

Returns

a SQRESULT

Remarks

This method works only with classes. A handle retrieved through a class can be later used to set or get values from one of the class instances. Handles retrieved from base classes are still valid in derived classes and respect inheritance rules.

pops a value from the stack and uses it as index to fetch the handle of a class member. The handle can be later used to set or get the member value using sq_getbyhandle(), sq_setbyhandle().

SQRELEASEHOOK sq_getreleasehook(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

Remarks

if the object that position idx is not an userdata, class instance or class the function returns NULL.

gets the release hook of the userdata, class instance or class at position idx in the stack.

SQChar *sq_getscratchpad(HSQUIRRELVM v, SQInteger minsize)

Parameters

• v (HSQUIRRELVM) – the target VM

• minsize (SQInteger) – the requested size for the scratchpad buffer

Remarks

the buffer is valid until the next call to sq_getscratchpad

returns a pointer to a memory buffer that is at least as big as minsize.

SQObjectType sq_getsize(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

Returns

the size of the value at the position idx in the stack

Remarks

this function only works with strings, arrays, tables, classes, instances, and userdata if the value is not a valid type, the function will return -1.

returns the size of a value at the idx position in the stack. If the value is a class or a class instance the size returned is the size of the userdata buffer (see sq_setclassudsize).

SQRESULT sq_getstring(HSQUIRRELVM v, SQInteger idx, const SQChar **c)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• c (const SQChar**) – a pointer to the pointer that will point to the string

Returns

a SQRESULT

gets a pointer to the string at the idx position in the stack.

SQRESULT sq_getstringandsize(HSQUIRRELVM v, SQInteger idx, const SQChar **c, SQInteger *size)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• c (const SQChar**) – a pointer to the pointer that will point to the string

• size (SQInteger*) – a pointer to a SQInteger which will receive the size of the string

Returns

a SQRESULT

gets a pointer to the string at the idx position in the stack; additionally retrieves its size.

SQRESULT sq_getthread(HSQUIRRELVM v, SQInteger idx, HSQUIRRELVM *v)

Parameters

• v (HSQUIRRELVM*) – the target VM

• idx (SQInteger) – an index in the stack

• v – A pointer to the variable that will store the thread pointer

Returns

a SQRESULT

gets a pointer to the thread the idx position in the stack.

SQObjectType sq_gettype(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

Returns

the type of the value at the position idx in the stack

returns the type of the value at the position idx in the stack

SQRESULT sq_gettypetag(HSQUIRRELVM v, SQInteger idx, SQUserPointer *typetag)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• typetag (SQUserPointer*) – a pointer to the variable that will store the tag

Returns

a SQRESULT

Remarks

the function works also with instances. if the taget object is an instance, the typetag of it’s base class is fetched.

gets the typetag of the object (userdata or class) at position idx in the stack.

SQRESULT sq_getuserdata(HSQUIRRELVM v, SQInteger idx, SQUserPointer *p, SQUserPointer *typetag)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• p (SQUserPointer*) – A pointer to the userpointer that will point to the userdata’s payload

• typetag (SQUserPointer*) – A pointer to a SQUserPointer that will store the userdata tag(see sq_settypetag). The parameter can be NULL.

Returns

a SQRESULT

gets a pointer to the value of the userdata at the idx position in the stack.

SQRESULT sq_getuserpointer(HSQUIRRELVM v, SQInteger idx, SQUserPointer *p)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• p (SQUserPointer*) – A pointer to the userpointer that will store the value

Returns

a SQRESULT

gets the value of the userpointer at the idx position in the stack.

void sq_newarray(HSQUIRRELVM v, SQInteger size)

Parameters

• v (HSQUIRRELVM) – the target VM

• size (SQInteger) – the size of the array that as to be created

creates a new array and pushes it in the stack

SQRESULT sq_newclass(HSQUIRRELVM v, SQBool hasbase)

Parameters

• v (HSQUIRRELVM) – the target VM

• hasbase (SQBool) – if the parameter is true the function expects a base class on top of the stack.

Returns

a SQRESULT

creates a new class object. If the parameter ‘hasbase’ is different than 0, the function pops a class from the stack and inherits the new created class from it. The new class is pushed in the stack.

void sq_newclosure(HSQUIRRELVM v, HSQFUNCTION func, SQInteger nfreevars)

Parameters

• v (HSQUIRRELVM) – the target VM

• func (HSQFUNCTION) – a pointer to a native-function

• nfreevars (SQInteger) – number of free variables(can be 0)

create a new native closure, pops n values set those as free variables of the new closure, and push the new closure in the stack.

void sq_newtable(HSQUIRRELVM v)

Parameters

• v (HSQUIRRELVM) – the target VM

creates a new table and pushes it in the stack

void sq_newtableex(HSQUIRRELVM v, SQInteger initialcapacity)

Parameters

• v (HSQUIRRELVM) – the target VM

• initialcapacity (SQInteger) – number of key/value pairs to preallocate

creates a new table and pushes it in the stack. This function allows you to specify the initial capacity of the table to prevent unnecessary rehashing when the number of slots required is known at creation-time.

SQUserPointer sq_newuserdata(HSQUIRRELVM v, SQUnsignedInteger size)

Parameters

• v (HSQUIRRELVM) – the target VM

• size (SQUnsignedInteger) – the size of the userdata that as to be created in bytes

creates a new userdata and pushes it in the stack

void sq_pushbool(HSQUIRRELVM v, SQBool b)

Parameters

• v (HSQUIRRELVM) – the target VM

• b (SQBool) – the bool that has to be pushed(SQTrue or SQFalse)

pushes a bool into the stack

void sq_pushfloat(HSQUIRRELVM v, SQFloat f)

Parameters

• v (HSQUIRRELVM) – the target VM

• f (SQFloat) – the float that has to be pushed

pushes a float into the stack

void sq_pushinteger(HSQUIRRELVM v, SQInteger n)

Parameters

• v (HSQUIRRELVM) – the target VM

• n (SQInteger) – the integer that has to be pushed

pushes an integer into the stack

void sq_pushnull(HSQUIRRELVM v)

Parameters

• v (HSQUIRRELVM) – the target VM

pushes a null value into the stack

void sq_pushstring(HSQUIRRELVM v, const SQChar *s, SQInteger len)

Parameters

• v (HSQUIRRELVM) – the target VM

• s (const SQChar*) – pointer to the string that has to be pushed

• len (SQInteger) – length of the string pointed by s

Remarks

if the parameter len is less than 0 the VM will calculate the length using strlen(s)

pushes a string in the stack

void sq_pushuserpointer(HSQUIRRELVM v, SQUserPointer p)

Parameters

• v (HSQUIRRELVM) – the target VM

• p (SQUserPointer) – the pointer that as to be pushed

pushes a userpointer into the stack

SQRESULT sq_setbyhandle(HSQUIRRELVM v, SQInteger idx, HSQMEMBERHANDLE *handle)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack pointing to the class

• handle (HSQMEMBERHANDLE*) – a pointer the member handle

Returns

a SQRESULT

pops a value from the stack and sets it to a class or instance member using a member handle (see sq_getmemberhandle)

SQRESULT sq_setclassudsize(HSQUIRRELVM v, SQInteger idx, SQInteger udsize)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack pointing to the class

• udsize (SQInteger) – size in bytes reserved for user data

Returns

a SQRESULT

Sets the user data size of a class. If a class ‘user data size’ is greater than 0. When an instance of the class is created additional space will be reserved at the end of the memory chunk where the instance is stored. The userpointer of the instance will also be automatically set to this memory area. This allows you to minimize allocations in applications that have to carry data along with the class instance.

SQRESULT sq_setclosureroot(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target closure

Returns

an SQRESULT

pops a table from the stack and sets it as root of the closure at position idx in the stack

SQRESULT sq_setinstanceup(HSQUIRRELVM v, SQInteger idx, SQUserPointer up)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• up (SQUserPointer) – an arbitrary user pointer

Returns

a SQRESULT

sets the userpointer of the class instance at position idx in the stack.

SQRESULT sq_setnativeclosurename(HSQUIRRELVM v, SQInteger idx, const SQChar *name)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target native closure

• name (const SQChar*) – the name that has to be set

Returns

an SQRESULT

sets the name of the native closure at the position idx in the stack. The name of a native closure is purely for debug purposes. The name is retrieved through the function sq_stackinfos() while the closure is in the call stack.

SQRESULT sq_setparamscheck(HSQUIRRELVM v, SQInteger nparamscheck, const SQChar *typemask)

Parameters

• v (HSQUIRRELVM) – the target VM

• nparamscheck (SQInteger) – defines the parameters number check policy (0 disables the param checking). If nparamscheck is greater than 0, the VM ensures that the number of parameters is exactly the number specified in nparamscheck (eg. if nparamscheck == 3 the function can only be called with 3 parameters). If nparamscheck is less than 0 the VM ensures that the closure is called with at least the absolute value of the number specified in nparamcheck (eg. nparamscheck == -3 will check that the function is called with at least 3 parameters). The hidden parameter ‘this’ is included in this number; free variables aren’t. If SQ_MATCHTYPEMASKSTRING is passed instead of the number of parameters, the function will automatically infer the number of parameters to check from the typemask (eg. if the typemask is “.sn”, it is like passing 3).

• typemask (const SQChar*) – defines a mask to validate the parametes types passed to the function. If the parameter is NULL, no typechecking is applied (default).

Remarks

The typemask consists in a zero terminated string that represent the expected parameter type. The types are expressed as follows: ‘o’ null, ‘i’ integer, ‘f’ float, ‘n’ integer or float, ‘s’ string, ‘t’ table, ‘a’ array, ‘u’ userdata, ‘c’ closure and nativeclosure, ‘g’ generator, ‘p’ userpointer, ‘v’ thread, ‘x’ instance(class instance), ‘y’ class, ‘b’ bool. and ‘.’ any type. The symbol ‘|’ can be used as ‘or’ to accept multiple types on the same parameter. There isn’t any limit on the number of ‘or’ that can be used. Spaces are ignored so can be inserted between types to increase readability. For instance to check a function that expect a table as ‘this’ a string as first parameter and a number or a userpointer as second parameter, the string would be “tsn|p” (table,string,number or userpointer). If the parameters mask is contains fewer parameters than ‘nparamscheck’, the remaining parameters will not be typechecked.

Sets the parameter validation scheme for the native closure at the top position in the stack. Allows you to validate the number of parameters accepted by the function and optionally their types. If the function call does not comply with the parameter schema set by sq_setparamscheck, an exception is thrown.

.eg

//example
SQInteger testy(HSQUIRRELVM v)
{
    SQUserPointer p;
    const SQChar *s;
    SQInteger i;
    //no type checking, if the call complies with the mask
    //surely the functions will succeed.
    sq_getuserdata(v,1,&p,NULL);
    sq_getstring(v,2,&s);
    sq_getinteger(v,3,&i);
    //... do something
    return 0;
}

//the reg code

//....stuff
sq_newclosure(v,testy,0);
//expects exactly 3 parameters(userdata,string,number)
sq_setparamscheck(v,3,_SC("usn"));
//....stuff

void sq_setreleasehook(HSQUIRRELVM v, SQInteger idx, SQRELEASEHOOK hook)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• hook (SQRELEASEHOOK) – a function pointer to the hook(see sample below)

Remarks

the function hook is called by the VM before the userdata memory is deleted.

sets the release hook of the userdata, class instance, or class at position idx in the stack.

.eg

/* tyedef SQInteger (*SQRELEASEHOOK)(SQUserPointer,SQInteger size); */

SQInteger my_release_hook(SQUserPointer p,SQInteger size)
{
    /* do something here */
    return 1;
}

SQRESULT sq_settypetag(HSQUIRRELVM v, SQInteger idx, SQUserPointer typetag)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• typetag (SQUserPointer) – an arbitrary SQUserPointer

Returns

a SQRESULT

sets the typetag of the object (userdata or class) at position idx in the stack.

void sq_tobool(HSQUIRRELVM v, SQInteger idx, SQBool *b)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

• b (SQBool*) – A pointer to the bool that will store the value

Remarks

if the object is not a bool the function converts the value to bool according to quirrel’s rules. For instance the number 1 will result in true, and the number 0 in false.

gets the value at position idx in the stack as bool.

void sq_tostring(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

converts the object at position idx in the stack to string and pushes the resulting string in the stack.

SQObjectType sq_typeof(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – an index in the stack

Returns

a SQRESULT

pushes the type name of the value at the position idx in the stack. It also invokes the _typeof metamethod for tables and class instances that implement it; in that case the pushed object could be something other than a string (is up to the _typeof implementation).