NAME
sqlite3_value_blob,
sqlite3_value_bytes,
sqlite3_value_bytes16,
sqlite3_value_double,
sqlite3_value_int,
sqlite3_value_int64,
sqlite3_value_text,
sqlite3_value_text16,
sqlite3_value_text16le,
sqlite3_value_text16be,
sqlite3_value_type,
sqlite3_value_numeric_type —
Obtaining SQL Values
SYNOPSIS
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*);
DESCRIPTION
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 3rd 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
sqlite3_column_blob(3),
sqlite3_value(3),
sqlite3_create_function(3),
sqlite3_value(3),
sqlite3_value_blob(3),
SQLITE_INTEGER(3),
sqlite3_value(3)