|
SQLite C Interface
Obtaining SQL Function Parameter Values
const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); int sqlite3_value_bytes16(sqlite3_value*); double sqlite3_value_double(sqlite3_value*); int sqlite3_value_int(sqlite3_value*); sqlite3_int64 sqlite3_value_int64(sqlite3_value*); 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_type(sqlite3_value*); int sqlite3_value_numeric_type(sqlite3_value*);
The C-language implementation of SQL functions and aggregates uses this set of interface routines to access the parameter values on the function or aggregate.
The xFunc (for scalar functions) or xStep (for aggregates) parameters to sqlite3_create_function() and sqlite3_create_function16() define callbacks that implement the SQL functions and aggregates. The 4th parameter to these callbacks is an array of pointers to protected sqlite3_value objects. There is one sqlite3_value object for each parameter to the SQL function. These routines are used to extract values from the sqlite3_value objects.
These routines work only with protected sqlite3_value objects. Any attempt to use these routines on an unprotected sqlite3_value object results in undefined behavior.
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.
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 ***