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

Invariants:

H15103 The sqlite3_value_blob(V) interface converts the protected sqlite3_value object V into a BLOB and then returns a pointer to the converted value.
H15106 The sqlite3_value_bytes(V) interface returns the number of bytes in the BLOB or string (exclusive of the zero terminator on the string) that was returned by the most recent call to sqlite3_value_blob(V) or sqlite3_value_text(V).
H15109 The sqlite3_value_bytes16(V) interface returns the number of bytes in the string (exclusive of the zero terminator on the string) that was returned by the most recent call to sqlite3_value_text16(V), sqlite3_value_text16be(V), or sqlite3_value_text16le(V).
H15112 The sqlite3_value_double(V) interface converts the protected sqlite3_value object V into a floating point value and returns a copy of that value.
H15115 The sqlite3_value_int(V) interface converts the protected sqlite3_value object V into a 64-bit signed integer and returns the lower 32 bits of that integer.
H15118 The sqlite3_value_int64(V) interface converts the protected sqlite3_value object V into a 64-bit signed integer and returns a copy of that integer.
H15121 The sqlite3_value_text(V) interface converts the protected sqlite3_value object V into a zero-terminated UTF-8 string and returns a pointer to that string.
H15124 The sqlite3_value_text16(V) interface converts the protected sqlite3_value object V into a zero-terminated 2-byte aligned UTF-16 native byte order string and returns a pointer to that string.
H15127 The sqlite3_value_text16be(V) interface converts the protected sqlite3_value object V into a zero-terminated 2-byte aligned UTF-16 big-endian string and returns a pointer to that string.
H15130 The sqlite3_value_text16le(V) interface converts the protected sqlite3_value object V into a zero-terminated 2-byte aligned UTF-16 little-endian string and returns a pointer to that string.
H15133 The sqlite3_value_type(V) interface returns one of SQLITE_NULL, SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, or SQLITE_BLOB as appropriate for the sqlite3_value object V.
H15136 The sqlite3_value_numeric_type(V) interface converts the protected sqlite3_value object V into either an integer or a floating point value if it can do so without loss of information, and returns one of SQLITE_NULL, SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, or SQLITE_BLOB as appropriate for the protected sqlite3_value object V after the conversion attempt.

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC