描述

 

以UTF-8字符串的形式返回列值。

 

C / C ++语法

 

 

PB语法

 

 

参数

 

pStmt

 

[in]语句句柄。

 

nCol

 

[in]应返回信息的列的索引。结果集的最左列有索引0。结果中的列数可以使用sqlite3_column_count确定。

 

返回值

 

列值作为指向空终止的UTF-8字符串的指针。

 

备注

 

如果SQL语句当前没有指向有效的行，或者如果列索引超出范围，则结果是未定义的。这些函数只能在最近调用sqlite3_step已返回SQLITE_ROW时调用，并且之后不再调用sqlite3_reset或sqlite3_finalize.如果在sqlite3_reset或sqlite3_finalize之后或在sqlite3_step返回了除了SQLITE_ROW之外的某些功能之后调用了这些功能，则结果未定义。sqlite3_reset或sqlite3_reset或sqlite3_finalize在sqlite3_column_text待处理之前从另一个线程调用，则结果未定义。

 

sqlite3_column_text返回的字符串，即使是空字符串，始终为零终止。

 

sqlite3_column_text尝试在适当的时候转换值。下表详细说明了所应用的转化：

 

 

请注意，当类型转换发生时，先前调用sqlite3_column_blob，sqlite3_column_text和/或sqlite3_column_text16返回的指针可能无效。在以下情况下可能会出现类型转换和指针无效：

 

初始内容是BLOB，并且sqlite3_column_text被调用。可能需要将零终止符添加到字符串。

 

初始内容为UTF-16文本，sqlite3_column_text被调用。内容必须转换为UTF-8。

 

UTF-16be和UTF-16le之间的转换总是完成，并且不会使先前的指针无效，尽管先前指针引用的缓冲区的内容当然会被修改。其他类型的转换在可能的情况下进行就位，但有时它们是不可能的，在这些情况下，先前的指针无效。

 

最安全和最简单的记住策略是通过以下方式之一调用这些功能：

 

sqlite3_column_text后跟sqlite3_column_bytes

sqlite3_column_blob后跟sqlite3_column_bytes

sqlite3_column_text16后跟sqlite3_column_bytes16

 

换句话说，您应先调用sqlite3_column_text，sqlite3_column_blob或sqlite3_column_text16以强制结果为所需的格式，然后调用sqlite3_column_bytes或sqlite3_column_bytes16查找结果的大小。不要将来电sqlite3_column_text或sqlite3_column_blob与sqlite3_column_bytes16的来电混合，不得将来电sqlite3_column_text16与sqlite3_column_bytes联系。

 

返回的指针是有效的，直到类型转换如上所述，或直到sqlite3_step或sqlite3_reset或sqlite3_finalize被调用为止。用于保存字符串和BLOB的内存空间将自动释放。不要传递返回的指针sqlite3_column_blob，sqlite3_column_text等进入sqlite3_free.

 

如果在评估任何这些功能时发生内存分配错误，则返回默认值。默认值为整数0，浮点数0.0或空指针。对sqlite3_errcode的后续调用将返回SQLITE_NOMEM。

 

C ++实现代码

 

SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt *pStmt, int i){

const unsigned char *val = sqlite3_value_text( columnMem(pStmt,i) );

columnMallocFailure(pStmt);

return val;

}