Small, Fast, Reliable.
Choose any three.

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 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 just like the corresponding sqlite3_column_* routines except that these routines take a single sqlite3_value* pointer instead of an sqlite3_stmt* pointer and an integer column number.

The sqlite3_value_text16() interface extracts a UTF16 string in the native byte-order of the host machine. The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces extract UTF16 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 order words if the value is original a string that looks like a number) then it is done. Otherwise no conversion occurs. The datatype after conversion is returned.

Please pay particular attention to the fact that the pointer that is 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. Or, if the sqlite3_value* argument comes from the sqlite3_column_value() interface, then these routines should be called from the same thread that ran sqlite3_column_value().

See also lists of Objects, Constants, and Functions.


This page last modified 2007/11/22 00:41:31 UTC