sqlite3_column()
Result Values From A Query
These routines form the "result set" 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 theprepared statementthat is being evaluated (thesqlite3_stmt*that was returned fromsqlite3_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. The number of columns in the result can be determined usingsqlite3_column_count(). 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 tosqlite3_step()has returnedSQLITE_ROWand neithersqlite3_reset()norsqlite3_finalize()have been called subsequently. If any of these routines are called aftersqlite3_reset()orsqlite3_finalize()or aftersqlite3_step()has returned something other thanSQLITE_ROW,the results are undefined. Ifsqlite3_step()orsqlite3_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 thedatatype codefor the initial data type of the result column. The returned value is one ofSQLITE_INTEGER,SQLITE_FLOAT,100)" rel="nofollow" target="_blank">SQLITE_TEXT,100)" rel="nofollow" target="_blank">SQLITE_BLOB,orSQLITE_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() usessqlite3_snprintf()to convert that value to a UTF-8 string and returns the number of bytes in that string. If the result is NULL,then sqlite3_column_bytes() returns zero. If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() routine returns the number of bytes in that BLOB or string. If the result is a UTF-8 string,then sqlite3_column_bytes16() converts the string to UTF-16 and then returns the number of bytes. If the result is a numeric value then sqlite3_column_bytes16() usessqlite3_snprintf()to convert that value to a UTF-16 string and returns the number of bytes in that string. If the result is NULL,then sqlite3_column_bytes16() returns zero. The values returned bysqlite3_column_bytes()andsqlite3_column_bytes16()do not include the zero terminators at the end of the string. For clarity: the values returned bysqlite3_column_bytes16()are 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 a NULL pointer. The object returned bysqlite3_column_value()is anunprotected sqlite3_valueobject. An unprotected sqlite3_value object may only be used withsqlite3_bind_value()andsqlite3_result_value(). If theunprotected sqlite3_valueobject returned bysqlite3_column_value()is used in any other way,including calls to routines likesqlite3_value_int(),sqlite3_value_text(),orsqlite3_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:
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:
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 references 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:
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 untilsqlite3_finalize()is called. The memory space used to hold strings and BLOBs is freed automatically. Donotpass the pointers returnedsqlite3_column_blob(),sqlite3_column_text(),etc. intosqlite3_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 tosqlite3_errcode()will returnSQLITE_NOMEM. (编辑:李大同) 【声明】本站内容均来自网络,其相关言论仅代表作者个人观点,不代表本站立场。若无意侵犯到您的权利,请及时与联系站长删除相关内容! |