描述

 

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

 

PB语法

 

 

参数

 

pStmt

 

[in]语句句柄。

 

vCol

 

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

 

返回值

 

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

 

备注

 

如果SQL语句当前没有指向有效的行，或者如果列索引超出范围，则结果是未定义的。只有当最近调用步已经返回SQLITE_ROW并且以后不再调用重启或最终确定时才可以调用这些函数。如果在重启或最终确定之后或在步返回了除了SQLITE_ROW之外的任何东西之后调用了这些功能中的任何一个，则结果未定义。步或重启或最终确定在ColumnText待处理之前从另一个线程调用，则结果未定义。

 

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

 

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

 

 

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

 

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

 

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

 

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

 

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

 

ColumnText后跟ColumnBytes

ColumnBlob，后跟ColumnBytes

ColumnTextW后跟ColumnBytesW

 

换句话说，您应该首先调用ColumnText，ColumnBlob或ColumnTextW来强制结果为所需的格式，然后调用Column_Bytes或ColumnBytesW以查找结果的大小。不要将来电ColumnText或ColumnBlob与ColumnBytesW的来电混合，不要将来电ColumnTextW与ColumnBytes通话。

 

返回的指针是有效的，直到类型转换发生如上所述，或直到步或重启或最终确定被调用。用于保存字符串和BLOB的内存空间将自动释放。不要传递返回的指针ColumnBlob，ColumnText，ColumnTextW等进入自由.

 

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