Efficient access to a SQLite BLOB field in a query.
sqlite-raw-blob-p object => boolean
sqlite-raw-blob-valid-p sqlite-raw-blob => boolean
sqlite-raw-blob-length sqlite-raw-blob => length
sqlite-raw-blob-ref sqlite-raw-blob index &optional foreign-element-type => value
copy-from-sqlite-raw-blob sqlite-raw-blob &key start end element-type => binary-array
replace-from-sqlite-raw-blob binary-array sqlite-raw-blob &key array-start array-end blob-start blob-end => binary-array
Any Lisp object.
An object of type sqlite-raw-blob.
A foreign element type.
Bounding index designators of sqlite-raw-blob.
A Lisp element type for a binary array.
Bounding index designators of binary-array.
Bounding index designators of sqlite-raw-blob.
A Lisp value of type matching foreign-element-type.
The sqlite-raw-blob interface allows a flexible and more efficient way to read from a SQLite BLOB object inside the dynamic extent of a Common SQL the iterative querying interface. The iterative querying interfaces include map-query, do-query, simple-do-query, loop with
each record, but does not include select and query.
Note that sqlite-raw-blob corresponds to the result of the C function
sqlite3_column_blob. You can read data from a BLOB using sqlite-raw-blob, but cannot modify it. For an interface that corresponds to the C structure
sqlite3_blob, see sqlite-blob.
You receive a sqlite-raw-blob object as the value from the query for fields where you specify the type as
:blob. This object is associated with a SQLite BLOB corresponding to the value of this field in the current row. For example, you can print the size (in bytes) of all the fields in the DataPointsColumn in SomeTable using this code:
(do-query ((raw-data-points) [select [DataPointsColumn :blob] :from [Sometable]]) (print (sqlite-raw-blob-length raw-data-points)))
sqlite-raw-blob-p returns true if object is of type sqlite-raw-blob and false otherwise.
For the functions
replace-from-sqlite-raw-blob, sqlite-raw-blob can be regarded as a handle to a foreign array of bytes, whose length in bytes as returned by
sqlite-raw-blob-length. When the element type argument (foreign-element-type or element-type) requires more than one byte, then the length of sqlite-raw-blob in elements is the length in bytes truncated by the number of bytes per element.
sqlite-raw-blob-ref is analogous to fli:dereference. The element type is specified by foreign-element-type, which defaults to
(:unsigned :byte). index must be a non-negative integer and smaller than the length of sqlite-raw-blob in elements.
sqlite-raw-blob-ref returns value in the same way that
(fli:dereference pointer-to-the-blob-data :index index :type foreign-element-type) would return it, if pointer-to-the-blob-data pointed to a foreign array with the same contents as sqlite-raw-blob.
copy-from-sqlite-raw-blob returns a Lisp array of element type element-type containing the elements of sqlite-raw-blob bounded by start and end. start and end specify the start and the end indices in elements (rather than bytes) into sqlite-raw-blob. start defaults to 0, and end to
nil, meaning the length of sqlite-raw-blob in elements. When supplied, start must be a non-negative integer and not bigger than the length of sqlite-raw-blob in elements, and end must be not smaller than start and not bigger than the length of sqlite-raw-blob in elements. element-type specifies the Lisp type of binary-array. It is upgraded by upgraded-array-element-type, and the result must be one of:
(unsigned-byte 64) (64-bit LispWorks only.)
(signed-byte 64) (64-bit LispWorks only.)
replace-from-sqlite-raw-blob is analogous to fli:replace-foreign-array. It replaces the elements of binary-array, bounded by array-start and array-end, by the elements of sqlite-raw-blob, bounded by blob-start and blob-end (all in elements). binary-array must be a binary array, which means an array with one of the element types listed in the previous paragraph. array-start and blob-start default to 0, array-end defaults to
nil, meaning the length of binary-array, and blob-end defaults to
nil, meaning the length of sqlite-raw-blob in elements. When supplied, array-start must be a non-negative integer and not bigger than the length of binary-array, array-end must be not smaller than array-start and not bigger than the length of binary-array, blob-start must be a non-negative integer and not bigger than the length of sqlite-raw-blob in elements, and blob-end must be not smaller than blob-start and not bigger than the length of sqlite-raw-blob in elements. The number of elements copied is the smaller of the difference between array-start and array-end, and the difference between blob-start and blob-end.
replace-from-sqlite-raw-blob returns binary-array.
A sqlite-raw-blob object is valid only inside the dynamic extent of the code that receives it from the iterative querying interface function or macro. Note that the sqlite-raw-blob is already invalid in the next iteration of the same operation. Trying to read data from an invalid sqlite-raw-blob using one of
replace-from-sqlite-raw-blob signals an error (of type sql-user-error).
sqlite-raw-blob-length still returns the correct value for an invalid sqlite-raw-blob.
sqlite-raw-blob-valid-p can be used to check if a sqlite-raw-blob is valid, but should be rarely useful.
LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:56