sqlite-raw-blob-p

sqlite-raw-blob-valid-p

sqlite-raw-blob-length

sqlite-raw-blob-ref

copy-from-sqlite-raw-blob

replace-from-sqlite-raw-blob Functions

Summary

Efficient access to a SQLite BLOB field in a query.

Package

sql

Signatures

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

Arguments

Values

Description

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

The function sqlite-raw-blob-p returns true if object is of type sqlite-raw-blob and false otherwise.

The function sqlite-raw-blob-length returns the length in bytes of the BLOB associated with sqlite-raw-blob.

For the functions sqlite-raw-blob-ref, copy-from-sqlite-raw-blob and 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.

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

The function 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:

• base-char
• bmp-char
• single-float
• double-float
• (unsigned-byte 8)
• (unsigned-byte 16)
• (unsigned-byte 32)
• (unsigned-byte 64) (64-bit LispWorks only.)
• (signed-byte 8)
• (signed-byte 16)
• (signed-byte 32)
• (signed-byte 64) (64-bit LispWorks only.)

The function 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 sqlite-raw-blob-ref, copy-from-sqlite-raw-blob or 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.

See also

map-query
do-query
simple-do-query
Loop Extensions in Common SQL
sqlite-raw-blob
sqlite-blob
23.3.1.5 Iteration