*** DRAFT ***

## SQLite C Interface

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

*** DRAFT ***