描述

 

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

 

C / C ++语法

 

 

PB语法

 

 

参数

 

pStmt

 

[in]语句句柄。

 

nCol

 

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

 

返回值

 

列值作为指向空端接UTF-16字符串的指针。

 

备注

 

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

 

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

 

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

 

 

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

 

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

 

初始内容为UTF-8文本，并调用sqlite3_column_text16.内容必须转换为UTF-16。

 

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的电话混合在一??起。

 

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

 

C ++实现代码

 

#ifndef SQLITE_OMIT_UTF16

SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt *pStmt, int i){

const void *val = sqlite3_value_text16( columnMem(pStmt,i) );

columnMallocFailure(pStmt);

return val;

}

#endif /* SQLITE_OMIT_UTF16 */