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_blob
→
BLOB value 


sqlite3_value_double
→
REAL value 


sqlite3_value_int
→
32-bit INTEGER value 


sqlite3_value_int64
→
64-bit INTEGER value 


sqlite3_value_pointer
→
Pointer value 


sqlite3_value_text
→
UTF-8 TEXT value 


sqlite3_value_text16
→
UTF-16 TEXT value in the native byteorder 


sqlite3_value_text16be
→
UTF-16be TEXT value 


sqlite3_value_text16le
→
UTF-16le TEXT value 


 
 
 


sqlite3_value_bytes
→
Size of a BLOB or a UTF-8 TEXT in bytes 



sqlite3_value_bytes16  
→ 
Size of UTF-16 TEXT in bytes 


sqlite3_value_type
→
Default 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,D) or sqlite3_result_pointer(C,P,X,D) 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_bind_pointer() routine is part of the pointer passing interface added for SQLite 3.20.0.

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.