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