4.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 squirrel 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, SQBool throwerror)
- 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. :param SQBool throwerror: if SQTrue the function sets the last error string in case of failure
- 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 (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 (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 *vm)
- Parameters:
v (HSQUIRRELVM) – the target VM
idx (SQInteger) – an index in the stack
vm (HSQUIRRELVM*) – 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 (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 (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 (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 squirrel’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).