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).