| blob | ||
|---|---|---|
 | Chapter 4. SIMPOL Built-In Types |  |
blob
Description
Blob types are value types and can contain either .nul,
.inf, the empty blob or a blob value of any size
(limited by memory). Blobs are made up of bytes. To provide for ease of
creation, it is possible to assign literal strings and string variables
to a blob using either the equals = symbol, the
.toblob() intrinsic function, or as part of the
blob.new() method.
Type Tags
None
Object Value
The value of a blob object is its content.
blob.new()
Description
Resizes an existing blob. If the blob's size is increased, it is padded with 0's. If it is decreased, the content is truncated.
Prototype
blob.new (
blob | string valuesize
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| value | None | blob | string | The value to be assigned to the new object. In value types the parameter to the new function is not a named parameter. Specifically in this object the initial parameter can be either a blob, a string that contains no characters greater than character value 255, or the named parameter that follows, which is an initialization size. |
| size | None | integer |
This parameter can be used in place of an initialization value in order to
create a blob with an initial size that has been initialized with 0
in each byte. This can be useful when manipulating items that will
be eventually placed in a single buffer and can be far more
efficient both in memory and speed than doing so in other ways. To
use this parameter, it is necessary use it by name in the
new() method.
|
Properties
| Property | Type | Description |
|---|---|---|
| size | integer | Contains the size of the blob in bytes (octets). |
| type | type | Specifies the integer type object. |
Methods
getblob()
Description
Returns a blob from a blob starting at position start
for length bytes.
Prototype
blobvar.getblob (
integer startlength
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| start | 1 | integer |
Contains the starting position for extracting the blob. If the value of this
is .nul or .inf then the
return value will be .nul.
|
| length | 1 | integer |
Contains the number of bytes to read from the blob. If the value of this is
.nul then the return value will also be
.nul. If it is .inf then
all of the bytes to the end of the blob will be read.
|
getinteger()
Description
Returns an integer from a blob starting at the byte for position
start. If any of the four parameters are equal
to .nul then the result will also be
.nul. If any of the following parameters:
start, lbo, or
signed is equal to .inf
then the result will be .nul.
Prototype
blobvar.getinteger (
integer startlengthlbosigned
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| start | 1 | integer | Returns an integer starting at the position named in this parameter. |
| length | 1 | integer |
The number of bytes to read from the blob to return as an integer value. If
this is equal to .inf, then all of the bytes
will be read to the end of the blob and interpreted as an
integer.
|
| lbo | .true | boolean |
Indicates whether the integer value should be interpreted as having been
stored with the least significant byte first
(.true) or with the most significant byte
first (.false).
|
| signed | .false | boolean | Indicates whether the integer will be interpreted as a signed or unsigned value. |
getstring()
Description
Returns a string from a blob starting at the byte for position
start for length
characters and taking into consideration the settings for character
size and logical byte order as well as the optional terminator
characters. If any of the first four parameters are equal to
.nul then the result will also be
.nul. If any of the following parameters:
start, charsize,
lbo, or terminator is
equal to .inf then the result will be
.nul.
Prototype
blobvar.getstring (
integer startlengthcharsizelboterminatorterminatedby
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| start | 1 | integer | Returns a string starting at the position named in this parameter. |
| length | 1 | integer |
The number of characters to read from the blob. If this is equal to
.inf, then characters will be read to the end
of the blob, or until a terminator is found (see
terminator parameter).
|
| charsize | 2 | integer | The number of bytes per character, which must be greater than 0. |
| lbo | .true | boolean |
Indicates whether characters should be interpreted as having been stored with
the least significant byte first (.true) or
with the most significant byte first (.false).
|
| terminator | "" | string |
A string made up of all the characters that can terminate the string being
read. As soon as any one character in the string of terminators
is read then reading stops and the string is returned. if the
value of this is .nul then no characters will
terminate the string being read.
|
| terminatedby | no object | string |
This parameter must be an object, not a string value such as a literal or
expression. If the reading of the string is terminated by finding
a character in the terminator string then
that character is returned in the
terminatedby object.
|
putblob()
Description
Outputs a blob into a blob starting at position start.
It is an error to try and write beyond the end of the blob.
Prototype
blobvar.putblob (
integer startblob
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| start | 1 | integer |
Writes a blob beginning at the starting position named in this parameter. If
the value of this is .nul or
.inf then the return value will be
.nul.
|
| blob | None | blob |
Contains the blob to be output. If the value of this is either
.nul or .inf, then no bytes
will be output.
|
putinteger()
Description
Outputs an integer to a blob starting at position start
for length bytes. It is an error to write past the end of the blob.
If either the start or
length parameter is equal to either
.nul or .inf then a runtime
error, "number out of range" will occur. If the
lbo parameter is equal to either
.nul or .inf or the
integer parameter is equal to either
.nul or .inf then no bytes will
be output.
Prototype
blobvar.putinteger (
integer startintegerlengthlbo
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| start | 1 | integer | Writes an integer starting at the position named in this parameter. |
| integer | None | integer | The value to output. |
| length | 1 | integer | The number of bytes to write to the blob. |
| lbo | .true | boolean |
Indicates whether the integer value should be stored with the least
significant byte first (.true) or with the
most significant byte first (.false).
|
putstring()
Description
Outputs a string to a blob starting at the byte for position
start for the length of the string and taking
into consideration the settings for character size and logical byte
order. It is an error to write past the end of the blob. If either of
the following parameters: charsize or
lbo is equal to either .nul
or .inf or if the string
parameter is equal to either .nul or
.inf then no bytes will be output. If the
start is equal to either
.nul or .inf then an error,
number out of range, will be generated.
Prototype
blobvar.putstring (
integer startstringcharsizelbo
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| start | 1 | integer | Writes a string to the blob starting at the position named in this parameter. |
| string | None | string | The string to be output. |
| charsize | 2 | integer | The number of bytes per character, which must be greater than 0. |
| lbo | .true | boolean |
Indicates whether characters have been stored with the least significant byte
first (.true) or with the most significant
byte first (.false).
|
setsize()
Description
Resizes an existing blob. If the blob's size is increased, it is padded with 0's. If it is decreased, the content is truncated.
Prototype
blobvar.setsize (
integer size
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| size | None | integer | Contains the new size for the blob. |
blob[]
Get
Subscripts
An integer giving the index position of the byte within the blob.
Description
Retrieves the integer value of the byte at the specified index position.
Set
Subscripts
An integer giving the index position of the byte within the blob.
Description
Assigns an integer value in the range of 0 to 255 to the specified index position in the blob.
Set Reference
Attempting to set a reference to an object is not supported.