3.6. Object manipulation

SQRESULT sq_arrayappend(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target array in the stack

Returns

a SQRESULT

Remarks

Only works on arrays.

pops a value from the stack and pushes it in the back of the array at the position idx in the stack.

SQRESULT sq_arrayinsert(HSQUIRRELVM v, SQInteger idx, SQInteger destpos)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target array in the stack

• destpos (SQInteger) – the position in the array where the item has to be inserted

Returns

a SQRESULT

Remarks

Only works on arrays.

pops a value from the stack and inserts it in an array at the specified position

SQRESULT sq_arraypop(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target array in the stack

Returns

a SQRESULT

Remarks

Only works on arrays.

pops a value from the back of the array at the position idx in the stack.

SQRESULT sq_arrayremove(HSQUIRRELVM v, SQInteger idx, SQInteger itemidx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target array in the stack

• itemidx (SQInteger) – the index of the item in the array that has to be removed

Returns

a SQRESULT

Remarks

Only works on arrays.

removes an item from an array

SQRESULT sq_arrayresize(HSQUIRRELVM v, SQInteger idx, SQInteger newsize)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target array in the stack

• newsize (SQInteger) – requested size of the array

Returns

a SQRESULT

Remarks

Only works on arrays. If newsize if greater than the current size the new array slots will be filled with nulls.

resizes the array at the position idx in the stack.

SQRESULT sq_arrayreverse(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target array in the stack

Returns

a SQRESULT

Remarks

Only works on arrays.

reverses an array in place.

SQRESULT sq_clear(HSQUIRRELVM v, SQInteger idx, SQBool freemem)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

• freemem (SQBool) – free allocated memory if needed. SQTrue by default.

Returns

a SQRESULT

Remarks

Only works on tables and arrays.

clears all the elements of the table/array at position idx in the stack.

SQRESULT sq_clone(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

pushes a clone of the table, array, or class instance at the position idx.

SQRESULT sq_deleteslot(HSQUIRRELVM v, SQInteger idx, SQBool pushval)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target table in the stack

• pushval (SQBool) – if this param is true the function will push the value of the deleted slot.

Returns

a SQRESULT

Remarks

invoke the _delslot metamethod in the table delegate. it only works on tables.

pops a key from the stack and delete the slot indexed by it from the table at position idx in the stack; if the slot does not exist, nothing happens.

SQRESULT sq_get(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

Remarks

this call will invokes the delegation system like a normal dereference it only works on tables, arrays, classes, instances and userdata; if the function fails, nothing will be pushed in the stack.

pops a key from the stack and performs a get operation on the object at the position idx in the stack; and pushes the result in the stack.

SQRESULT sq_getbase(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target class in the stack

Returns

a SQRESULT

pushes the base class of the ‘class’ at stored position idx in the stack.

SQRESULT sq_getclass(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target class instance in the stack

Returns

a SQRESULT

pushes the class of the ‘class instance’ at stored position idx in the stack.

SQRESULT sq_getdelegate(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

pushes the current delegate of the object at the position idx in the stack.

const SQChar *sq_getfreevariable(HSQUIRRELVM v, SQInteger idx, SQInteger nval)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack(closure)

• nval (SQInteger) – 0 based index of the free variable(relative to the closure).

Returns

the name of the free variable for pure quirrel closures. NULL in case of error or if the index of the variable is out of range. In case the target closure is a native closure, the return name is always “@NATIVE”.

Remarks

The function works for both quirrel closure and native closure.

gets the value of the free variable of the closure at the position idx in the stack.

SQRESULT sq_getweakrefval(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target weak reference

Returns

a SQRESULT

Remarks

if the function fails, nothing is pushed in the stack.

pushes the object pointed by the weak reference at position idx in the stack.

SQBool sq_instanceof(HSQUIRRELVM v)

Parameters

• v (HSQUIRRELVM) – the target VM

Returns

SQTrue if the instance at position -2 in the stack is an instance of the class object at position -1 in the stack.

Remarks

The function doesn’t pop any object from the stack.

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

SQRESULT sq_newmember(HSQUIRRELVM v, SQInteger idx, SQBool bstatic)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target table in the stack

• bstatic (SQBool) – if SQTrue creates a static member.

Returns

a SQRESULT

pops a key and a value from the stack and performs a new slot operation on the class that is at position idx in the stack; if the slot does not exist, it will be created.

SQRESULT sq_newslot(HSQUIRRELVM v, SQInteger idx, SQBool bstatic)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target table in the stack

• bstatic (SQBool) – if SQTrue creates a static member. This parameter is only used if the target object is a class.

Returns

a SQRESULT

Remarks

Invokes the _newslot metamethod in the table delegate. it only works on tables and classes.

pops a key and a value from the stack and performs a set operation on the table or class that is at position idx in the stack, if the slot does not exist it will be created.

SQRESULT sq_next(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

Pushes in the stack the next key and value of an array, table, or class slot. To start the iteration this function expects a null value on top of the stack; at every call the function will substitute the null value with an iterator and push key and value of the container slot. Every iteration the application has to pop the previous key and value but leave the iterator(that is used as reference point for the next iteration). The function will fail when all slots have been iterated(see Tables and arrays manipulation).

SQRESULT sq_rawdeleteslot(HSQUIRRELVM v, SQInteger idx, SQBool pushval)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target table in the stack

• pushval (SQBool) – if this param is true the function will push the value of the deleted slot.

Returns

a SQRESULT

Deletes a slot from a table without employing the _delslot metamethod. Pops a key from the stack and delete the slot indexed by it from the table at position idx in the stack; if the slot does not exist nothing happens.

SQRESULT sq_rawget(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

Remarks

Only works on tables and arrays.

pops a key from the stack and performs a get operation on the object at position idx in the stack, without employing delegation or metamethods.

SQRESULT sq_rawset(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

Remarks

it only works on tables and arrays. if the function fails nothing will be pushed in the stack.

pops a key and a value from the stack and performs a set operation on the object at position idx in the stack, without employing delegation or metamethods.

SQRESULT sq_set(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

Remarks

this call will invoke the delegation system like a normal assignment, it only works on tables, arrays and userdata.

pops a key and a value from the stack and performs a set operation on the object at position idx in the stack.

SQRESULT sq_setdelegate(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

Returns

a SQRESULT

Remarks

to remove the delegate from an object, set a null value.

pops a table from the stack and sets it as the delegate of the object at the position idx in the stack.

SQRESULT sq_setfreevariable(HSQUIRRELVM v, SQInteger idx, SQInteger nval)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index of the target object in the stack

• nval (SQInteger) – 0 based index of the free variable(relative to the closure).

Returns

a SQRESULT

pops a value from the stack and sets it as a free variable of the closure at the position idx in the stack.

void sq_weakref(HSQUIRRELVM v, SQInteger idx)

Parameters

• v (HSQUIRRELVM) – the target VM

• idx (SQInteger) – index to the target object in the stack

Returns

a SQRESULT

Remarks

if the object at idx position is one of (integer, float, bool, null), the object itself is pushed instead of a weak ref.

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