3. The Blob library

The blob library implements binary data manipulations routines. The library is based on blob objects that represent 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 length of the stream

blob.readblob(size)
Arguments

  • size (int()) – number of bytes to read

read n bytes from the stream and returns 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 parameter.

type can have the following values:

parameter

return description

return type

‘l’

processor dependent, 32bits on 32bits processors, 64bits on 64bits processors

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

creates string from blob

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 parameter

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