3. The Blob library

The blob library implements binary data manipulations routines. The library is based on blob objects that rapresent a buffer of arbitrary binary data.

3.1. Squirrel API

3.1.1. Global symbols

castf2i(f)

casts a float to a int

casti2f(n)

casts a int to a float

swap2(n)

swap the byte order of a number (like it would be a 16bits integer)

swap4(n)

swap the byte order of an integer

swapfloat(n)

swaps the byteorder of a float

3.1.2. The blob class

The blob object is a buffer of arbitrary binary data. The object behaves like a file stream, it has a read/write pointer and it automatically grows if data is written out of his boundary. A blob can also be accessed byte by byte through the [] operator.

class blob(size)
Arguments:
  • size (int) – initial size of the blob

returns a new instance of a blob class of the specified size in bytes

blob.eos()

returns a non null value if the read/write pointer is at the end of the stream.

blob.flush()

flushes the stream.return a value != null if succeded, otherwise returns null

blob.len()

returns the lenght of the stream

blob.readblob(size)
Arguments:
  • size (int) – number of bytes to read

read n bytes from the stream and retuns them as blob

blob.readn(type)
Arguments:
  • type (int) – type of the number to read

reads a number from the stream according to the type pameter.

type can have the following values:

parameter return description return type
‘l’ processor dependent, 32bits on 32bits processors, 64bits on 64bits prcessors integer
‘i’ 32bits number integer
‘s’ 16bits signed integer integer
‘w’ 16bits unsigned integer integer
‘c’ 8bits signed integer integer
‘b’ 8bits unsigned integer integer
‘f’ 32bits float float
‘d’ 64bits float float
blob.resize(size)
Arguments:
  • size (int) – the new size of the blobl in bytes

resizes the blob to the specified size

blob.seek(offset[, origin])
Arguments:
  • offset (int) – indicates the number of bytes from origin.
  • origin (int) –

    origin of the seek

    ‘b’ beginning of the stream
    ‘c’ current location
    ‘e’ end of the stream

Moves the read/write pointer to a specified location.

Note

If origin is omitted the parameter is defaulted as ‘b’(beginning of the stream).

blob.swap2()

swaps the byte order of the blob content as it would be an array of 16bits integers

blob.swap4()

swaps the byte order of the blob content as it would be an array of 32bits integers

blob.tell()

returns the read/write pointer absolute position

blob.writeblob(src)
Arguments:
  • src (blob) – the source blob containing the data to be written

writes a blob in the stream

blob.writen(n, type)
Arguments:
  • n (number) – the value to be written
  • type (int) – type of the number to write

writes a number in the stream formatted according to the type pameter

type can have the following values:

parameter return description
‘i’ 32bits number
‘s’ 16bits signed integer
‘w’ 16bits unsigned integer
‘c’ 8bits signed integer
‘b’ 8bits unsigned integer
‘f’ 32bits float
‘d’ 64bits float

3.2. C API

SQRESULT sqstd_register_bloblib(HSQUIRRELVM v)
Parameters:
  • v (HSQUIRRELVM) – the target VM
Returns:

an SQRESULT

Remarks:

The function aspects a table on top of the stack where to register the global library functions.

initializes and registers the blob library in the given VM.

SQRESULT sqstd_getblob(HSQUIRRELVM v, SQInteger idx, SQUserPointer* ptr)
Parameters:
  • v (HSQUIRRELVM) – the target VM
  • idx (SQInteger) – and index in the stack
  • ptr (SQUserPointer*) – A pointer to the userpointer that will point to the blob’s payload
Returns:

an SQRESULT

retrieve the pointer of a blob’s payload from an arbitrary position in the stack.

SQInteger sqstd_getblobsize(HSQUIRRELVM v, SQInteger idx)
Parameters:
  • v (HSQUIRRELVM) – the target VM
  • idx (SQInteger) – and index in the stack
Returns:

the size of the blob at idx position

retrieves the size of a blob’s payload from an arbitrary position in the stack.

SQUserPointer sqstd_createblob(HSQUIRRELVM v, SQInteger size)
Parameters:
  • v (HSQUIRRELVM) – the target VM
  • size (SQInteger) – the size of the blob payload that has to be created
Returns:

a pointer to the newly created blob payload

creates a blob with the given payload size and pushes it in the stack.