Creating objects

Pushing C values into the VM, making containers and classes, and reading values back out.

This is the largest section of the header. It holds three related jobs: the sq_push* family puts a C value on the stack, the sq_new* family creates a Quirrel object, and the sq_get* family converts a value on the stack back to C.

A sq_get* returns SQRESULT because the conversion can fail. A read of a string from a slot that holds an integer is an error, not a coercion. A string pointer obtained this way is owned by the VM. It stays valid only while the value is reachable from the stack or from a handle you hold a reference to. See Holding references from C.

Use sq_new_closure_slot_from_decl_string to register a native function, not sq_newclosure plus a type mask. The declaration string gives the function parameter names and types. Every signature on this site is built from one.

SQUserPointer sq_newuserdata(HSQUIRRELVM v, SQUnsignedInteger size)

Creates a new userdata and pushes it in the stack.

void sq_newtable(HSQUIRRELVM v)

Creates a new table and pushes it in the stack.

void sq_newtableex(HSQUIRRELVM v, SQInteger initialcapacity)

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.

void sq_newarray(HSQUIRRELVM v, SQInteger size)

Creates a new array and pushes it in the stack.

SQRESULT sq_new_closure_slot_from_decl_string(HSQUIRRELVM v, SQFUNCTION func, SQUnsignedInteger nfreevars, const char *function_decl, const char *docstring)

Creates a native closure from a readable declaration string and stores it as a slot, which is how a binding gets real parameter names and types.

void sq_newclosure(HSQUIRRELVM v, SQFUNCTION func, SQUnsignedInteger nfreevars)

Creates a native closure from a C function, taking n values off the stack as its free variables, and pushes it.

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

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.

SQRESULT sq_bindenv(HSQUIRRELVM v, SQInteger idx)

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.

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

Pushes a string in the stack.

void sq_pushfloat(HSQUIRRELVM v, SQFloat f)

Pushes a float into the stack.

void sq_pushinteger(HSQUIRRELVM v, SQInteger n)

Pushes an integer into the stack.

void sq_pushbool(HSQUIRRELVM v, SQBool b)

Pushes a bool into the stack.

void sq_pushuserpointer(HSQUIRRELVM v, SQUserPointer p)

Pushes a userpointer into the stack.

void sq_pushnull(HSQUIRRELVM v)

Pushes a null value into the stack.

void sq_pushthread(HSQUIRRELVM v, HSQUIRRELVM thread)

Pushes a thread (a VM handle) onto the stack of another VM.

SQObjectType sq_gettype(HSQUIRRELVM v, SQInteger idx)

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

SQRESULT sq_typeof(HSQUIRRELVM v, SQInteger idx)

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

SQInteger sq_getsize(HSQUIRRELVM v, SQInteger idx)

Returns the element count of the value at idx. For a class or instance this is the size of its userdata buffer, not a member count.

SQHash sq_gethash(HSQUIRRELVM v, SQInteger idx)

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

SQRESULT sq_getbase(HSQUIRRELVM v, SQInteger idx)

Pushes the base class of the 'class' at stored position idx in the stack.

SQBool sq_instanceof(HSQUIRRELVM v)

Determines if an object is an instance of a certain class. Expects an instance and a class in the stack.

SQRESULT sq_tostring(HSQUIRRELVM v, SQInteger idx)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Gets a pointer to the thread at the idx position in the stack.

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

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

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

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

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

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

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

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

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

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

SQRELEASEHOOK sq_getreleasehook(HSQUIRRELVM v, SQInteger idx)

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

char *sq_getscratchpad(HSQUIRRELVM v, SQInteger minsize)

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

SQRESULT sq_getfunctioninfo(HSQUIRRELVM v, SQInteger level, SQFunctionInfo *fi)

Fills a function info struct for the closure at position idx.

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

Retrieves number of parameters and number of freevariables from a Quirrel closure.

SQRESULT sq_getclosurename(HSQUIRRELVM v, SQInteger idx)

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_setnativeclosurename(HSQUIRRELVM v, SQInteger idx, const char *name)

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_setnativeclosuredocstring(HSQUIRRELVM v, SQInteger idx, const char *docstring)

Attaches a documentation string to a native closure.

SQRESULT sq_setobjectdocstring(HSQUIRRELVM v, const HSQOBJECT *obj, const char *docstring)

Attaches a documentation string to an object.

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

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

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

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_setclassudsize(HSQUIRRELVM v, SQInteger idx, SQInteger udsize)

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_newclass(HSQUIRRELVM v, SQBool hasbase)

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.

SQRESULT sq_createinstance(HSQUIRRELVM v, SQInteger idx)

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_getclass(HSQUIRRELVM v, SQInteger idx)

Pushes the class of the 'class instance' at stored position idx in the stack.

void sq_weakref(HSQUIRRELVM v, SQInteger idx)

Pushes a weak reference to the object at position idx in the stack.

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

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

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

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

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

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

Native fields

A class whose instances carry a C++ struct can expose the fields of that struct directly, without a getter closure per field.

SQRESULT sq_registernativefield(HSQUIRRELVM v, SQInteger classidx, const char *name, SQInteger offset, SQInteger fieldtype)

Exposes a field of a C++ struct held in inline userdata as a slot on the class.