*** DRAFT ***
Search for:

SQLite C Interface

Obtaining SQL Values

const void *sqlite3_value_blob(sqlite3_value*);
double sqlite3_value_double(sqlite3_value*);
int sqlite3_value_int(sqlite3_value*);
sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
void *sqlite3_value_pointer(sqlite3_value*, const char*);
const unsigned char *sqlite3_value_text(sqlite3_value*);
const void *sqlite3_value_text16(sqlite3_value*);
const void *sqlite3_value_text16le(sqlite3_value*);
const void *sqlite3_value_text16be(sqlite3_value*);
int sqlite3_value_bytes(sqlite3_value*);
int sqlite3_value_bytes16(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
int sqlite3_value_numeric_type(sqlite3_value*);

Summary:

sqlite3_value_blobBLOB value
sqlite3_value_doubleREAL value
sqlite3_value_int32-bit INTEGER value
sqlite3_value_int6464-bit INTEGER value
sqlite3_value_pointerPointer value
sqlite3_value_textUTF-8 TEXT value
sqlite3_value_text16UTF-16 TEXT value in the native byteorder
sqlite3_value_text16beUTF-16be TEXT value
sqlite3_value_text16leUTF-16le TEXT value
   
sqlite3_value_bytesSize of a BLOB or a UTF-8 TEXT in bytes
sqlite3_value_bytes16   →  Size of UTF-16 TEXT in bytes
sqlite3_value_typeDefault datatype of the value
sqlite3_value_numeric_type   →  Best numeric datatype of the value

Details:

These routines extract type, size, and content information from protected sqlite3_value objects. Protected sqlite3_value objects are used to pass parameter information into implementation of application-defined SQL functions and virtual tables.

These routines work only with protected sqlite3_value objects. Any attempt to use these routines on an unprotected sqlite3_value is not threadsafe.

These routines work just like the corresponding column access functions except that these routines take a single protected sqlite3_value object pointer instead of a sqlite3_stmt* pointer and an integer column number.

The sqlite3_value_text16() interface extracts a UTF-16 string in the native byte-order of the host machine. The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces extract UTF-16 strings as big-endian and little-endian respectively.

If sqlite3_value object V was initialized using sqlite3_bind_pointer(S,I,P,X) or sqlite3_result_pointer(C,P,X) and if X and Y are strings that compare equal according to strcmp(X,Y), then sqlite3_value_pointer(V,Y) will return the pointer P. Otherwise, sqlite3_value_pointer(V,Y) returns a NULL.

The sqlite3_value_type(V) interface returns the datatype code for the initial datatype of the sqlite3_value object V. The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. Other interfaces might change the datatype for an sqlite3_value object. For example, if the datatype is initially SQLITE_INTEGER and sqlite3_value_text(V) is called to extract a text value for that integer, then subsequent calls to sqlite3_value_type(V) might return SQLITE_TEXT. Whether or not a persistent internal datatype conversion occurs is undefined and may change from one release of SQLite to the next.

The sqlite3_value_numeric_type() interface attempts to apply numeric affinity to the value. This means that an attempt is made to convert the value to an integer or floating point. If such a conversion is possible without loss of information (in other words, if the value is a string that looks like a number) then the conversion is performed. Otherwise no conversion occurs. The datatype after conversion is returned.

Please pay particular attention to the fact that the pointer returned from sqlite3_value_blob(), sqlite3_value_text(), or sqlite3_value_text16() can be invalidated by a subsequent call to sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite3_value_text(), or sqlite3_value_text16().

These routines must be called from the same thread as the SQL function that supplied the sqlite3_value* parameters.

See also lists of Objects, Constants, and Functions.

*** DRAFT ***