Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

## Result Values From A Query

>     const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
>     int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
>     int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
>     double sqlite3_column_double(sqlite3_stmt*, int iCol);
>     int sqlite3_column_int(sqlite3_stmt*, int iCol);
>     sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
>     const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
>     const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
>     int sqlite3_column_type(sqlite3_stmt*, int iCol);
>     sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

These routines form the "result set query" interface.

These routines return information about a single column of the current result row of a query. In every case the first argument is a pointer to the prepared statement that is being evaluated (the sqlite3_stmt* that was returned from sqlite3_prepare_v2() or one of its variants) and the second argument is the index of the column for which information should be returned. The leftmost column of the result set has the index 0.

If the SQL statement does not currently point to a valid row, or if the column index is out of range, the result is undefined. These routines may only be called when the most recent call to sqlite3_step() has returned SQLITE_ROW and neither sqlite3_reset() nor sqlite3_finalize() have been called subsequently. If any of these routines are called after sqlite3_reset() or sqlite3_finalize() or after sqlite3_step() has returned something other than SQLITE_ROW, the results are undefined. If sqlite3_step() or sqlite3_reset() or sqlite3_finalize() are called from a different thread while any of these routines are pending, then the results are undefined.

The sqlite3_column_type() routine returns the datatype code for the initial data type of the result column. The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. The value returned by sqlite3_column_type() is only meaningful if no type conversions have occurred as described below. After a type conversion, the value returned by sqlite3_column_type() is undefined. Future versions of SQLite may change the behavior of sqlite3_column_type() following a type conversion.

If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() routine returns the number of bytes in that BLOB or string. If the result is a UTF-16 string, then sqlite3_column_bytes() converts the string to UTF-8 and then returns the number of bytes. If the result is a numeric value then sqlite3_column_bytes() uses sqlite3_snprintf() to convert that value to a UTF-8 string and returns the number of bytes in that string. The value returned does not include the zero terminator at the end of the string. For clarity: the value returned is the number of bytes in the string, not the number of characters.

Strings returned by sqlite3_column_text() and sqlite3_column_text16(), even empty strings, are always zero terminated. The return value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary pointer, possibly even a NULL pointer.

The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() but leaves the result in UTF-16 in native byte order instead of UTF-8. The zero terminator is not included in this count.

The object returned by sqlite3_column_value() is an unprotected sqlite3_value object. An unprotected sqlite3_value object may only be used with sqlite3_bind_value() and sqlite3_result_value(). If the unprotected sqlite3_value object returned by sqlite3_column_value() is used in any other way, including calls to routines like sqlite3_value_int(), sqlite3_value_text(), or sqlite3_value_bytes(), then the behavior is undefined.

These routines attempt to convert the value where appropriate. For example, if the internal representation is FLOAT and a text result is requested, sqlite3_snprintf() is used internally to perform the conversion automatically. The following table details the conversions that are applied:

> Internal Type | Requested Type | Conversion
> --- | --- | ---
> NULL | INTEGER | Result is 0
> NULL | FLOAT | Result is 0.0
> NULL | TEXT | Result is NULL pointer
> NULL | BLOB | Result is NULL pointer
> INTEGER | FLOAT | Convert from integer to float
> INTEGER | TEXT | ASCII rendering of the integer
> INTEGER | BLOB | Same as INTEGER->TEXT
> FLOAT | INTEGER | Convert from float to integer
> FLOAT | TEXT | ASCII rendering of the float
> FLOAT | BLOB | Same as FLOAT->TEXT
> TEXT | INTEGER | Use atoi()
> TEXT | FLOAT | Use atof()
> TEXT | BLOB | No change
> BLOB | INTEGER | Convert to TEXT then use atoi()
> BLOB | FLOAT | Convert to TEXT then use atof()
> BLOB | TEXT | Add a zero terminator if needed

The table above makes reference to standard C library functions atoi() and atof(). SQLite does not really use these functions. It has its own equivalent internal routines. The atoi() and atof() names are used in the table for brevity and because they are familiar to most C programmers.

Note that when type conversions occur, pointers returned by prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16() may be invalidated. Type conversions and pointer invalidations might occur in the following cases:

- The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() is called. A zero-terminator might need to be added to the string.
- The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() is called. The content must be converted to UTF-16.
- The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() is called. The content must be converted to UTF-8.

Conversions between UTF-16be and UTF-16le are always done in place and do not invalidate a prior pointer, though of course the content of the buffer that the prior pointer points to will have been modified. Other kinds of conversion are done in place when it is possible, but sometimes they are not possible and in those cases prior pointers are invalidated.

The safest and easiest to remember policy is to invoke these routines in one of the following ways:

- sqlite3_column_text() followed by sqlite3_column_bytes()
- sqlite3_column_blob() followed by sqlite3_column_bytes()
- sqlite3_column_text16() followed by sqlite3_column_bytes16()

In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), or sqlite3_column_text16() first to force the result into the desired format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to find the size of the result. Do not mix calls to sqlite3_column_text() or sqlite3_column_blob() with calls to sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().

The pointers returned are valid until a type conversion occurs as described above, or until sqlite3_step() or sqlite3_reset() or sqlite3_finalize() is called. The memory space used to hold strings and BLOBs is freed automatically. Do not pass the pointers returned sqlite3_column_blob(), sqlite3_column_text(), etc. into sqlite3_free().

If a memory allocation error occurs during the evaluation of any of these routines, a default value is returned. The default value is either the integer 0, the floating point number 0.0, or a NULL pointer. Subsequent calls to sqlite3_errcode() will return SQLITE_NOMEM.

### Invariants:

H13803 | The sqlite3_column_blob(S,N) interface converts the Nth column in the current row of the result set for the prepared statement S into a BLOB and then returns a pointer to the converted value.
H13806 | The sqlite3_column_bytes(S,N) 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_column_blob(S,N) or sqlite3_column_text(S,N).
H13809 | The sqlite3_column_bytes16(S,N) 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_column_text16(S,N).
H13812 | The sqlite3_column_double(S,N) interface converts the Nth column in the current row of the result set for the prepared statement S into a floating point value and returns a copy of that value.
H13815 | The sqlite3_column_int(S,N) interface converts the Nth column in the current row of the result set for the prepared statement S into a 64-bit signed integer and returns the lower 32 bits of that integer.
H13818 | The sqlite3_column_int64(S,N) interface converts the Nth column in the current row of the result set for the prepared statement S into a 64-bit signed integer and returns a copy of that integer.
H13821 | The sqlite3_column_text(S,N) interface converts the Nth column in the current row of the result set for the prepared statement S into a zero-terminated UTF-8 string and returns a pointer to that string.
H13824 | The sqlite3_column_text16(S,N) interface converts the Nth column in the current row of the result set for the prepared statement S into a zero-terminated 2-byte aligned UTF-16 native byte order string and returns a pointer to that string.
H13827 | The sqlite3_column_type(S,N) interface returns one of SQLITE_NULL, SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, or SQLITE_BLOB as appropriate for the Nth column in the current row of the result set for the prepared statement S.
H13830 | The sqlite3_column_value(S,N) interface returns a pointer to an unprotected sqlite3_value object for the Nth column in the current row of the result set for the prepared statement S.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/08/11 17:57:43 UTC