SQLite中文网

SQLite C 接口

查询的结果值

const void *sqlite3_column_blob(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);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);

概括：

sqlite3_column_blob→BLOB 结果
sqlite3_column_double→真正的结果
sqlite3_column_int→32 位整数结果
sqlite3_column_int64→64 位整数结果
sqlite3_column_text→UTF-8 文本结果
sqlite3_column_text16→UTF-16 文本结果
sqlite3_column_value→作为 未受保护的 sqlite3_value对象的结果。
   
sqlite3_column_bytes→BLOB 或 UTF-8 TEXT 结果的大小（以字节为单位）
sqlite3_column_bytes16   →  UTF-16 TEXT 的字节大小
sqlite3_column_type→结果的默认数据类型

细节：

这些例程返回有关查询当前结果行的单个列的信息。在每种情况下，第一个参数是指向正在评估的准备语句的指针（ 从sqlite3_prepare_v2()或其变体之一返回的sqlite3_stmt* ），第二个参数是应返回信息的列的索引. 结果集最左边的列的索引为 0。结果中的列数可以使用 sqlite3_column_count()确定。

如果 SQL 语句当前未指向有效行，或者列索引​​超出范围，则结果未定义。这些例程只能在最近调用 sqlite3_step()返回SQLITE_ROW并且随后既没有 调用 sqlite3_reset( )也没有调用sqlite3_finalize()时调用。如果在sqlite3_reset()或 sqlite3_finalize()之后或在sqlite3_step()返回SQLITE_ROW以外的内容之后调用这些例程中的任何一个，则结果是不确定的。如果sqlite3_step()或sqlite3_reset()或sqlite3_finalize() 当这些例程中的任何一个挂起时从不同的线程调用，那么结果是未定义的。

前六个接口（_blob、_double、_int、_int64、_text 和 _text16）均以特定数据格式返回结果列的值。如果结果列最初不是请求的格式（例如，如果查询返回一个整数但 sqlite3_column_text() 接口用于提取值）则执行自动类型转换。

sqlite3_column_type() 例程返回 结果列的初始数据类型的数据类型代码。返回值是SQLITE_INTEGER、 SQLITE_FLOAT、SQLITE_TEXT、SQLITE_BLOB或SQLITE_NULL 之一. sqlite3_column_type() 的返回值可用于决定应使用前六个接口中的哪一个来提取列值。sqlite3_column_type() 返回的值只有在相关值没有发生自动类型转换时才有意义。类型转换后，调用 sqlite3_column_type() 的结果是未定义的，但无害。SQLite 的未来版本可能会在类型转换后更改 sqlite3_column_type() 的行为。

如果结果是 BLOB 或 TEXT 字符串，则可以使用 sqlite3_column_bytes() 或 sqlite3_column_bytes16() 接口来确定该 BLOB 或字符串的大小。

如果结果是 BLOB 或 UTF-8 字符串，则 sqlite3_column_bytes() 例程返回该 BLOB 或字符串中的字节数。如果结果是 UTF-16 字符串，则 sqlite3_column_bytes() 会将字符串转换为 UTF-8，然后返回字节数。如果结果是一个数值，则 sqlite3_column_bytes() 使用 sqlite3_snprintf()将该值转换为 UTF-8 字符串并返回该字符串中的字节数。如果结果为 NULL，则 sqlite3_column_bytes() 返回零。

如果结果是 BLOB 或 UTF-16 字符串，则 sqlite3_column_bytes16() 例程返回该 BLOB 或字符串中的字节数。如果结果是 UTF-8 字符串，则 sqlite3_column_bytes16() 会将字符串转换为 UTF-16，然后返回字节数。如果结果是数值，则 sqlite3_column_bytes16() 使用 sqlite3_snprintf()将该值转换为 UTF-16 字符串并返回该字符串中的字节数。如果结果为 NULL，则 sqlite3_column_bytes16() 返回零。

sqlite3_column_bytes()和 sqlite3_column_bytes16()返回的值不包括字符串末尾的零终止符。为清楚起见： sqlite3_column_bytes()和sqlite3_column_bytes16()返回的值是字符串中的字节数，而不是字符数。

sqlite3_column_text() 和 sqlite3_column_text16() 返回的字符串，即使是空字符串，也始终以零结尾。零长度 BLOB 的 sqlite3_column_blob() 的返回值是 NULL 指针。

sqlite3_column_text16() 返回的字符串始终具有平台原生的字节序，无论数据库的文本编码设置如何。

警告：sqlite3_column_value()返回的对象是一个 不受保护的 sqlite3_value对象。在多线程环境中，未受保护的 sqlite3_value 对象只能安全地与 sqlite3_bind_value()和sqlite3_result_value()一起使用。如果以任何其他方式使用sqlite3_column_value()返回的未受保护的 sqlite3_value对象 ，包括调用sqlite3_value_int()、sqlite3_value_text()或sqlite3_value_bytes()等例程，则该行为不是线程安全的。因此，sqlite3_column_value() 接口通常只在实现中有用 应用程序定义的 SQL 函数或虚拟表，不在顶级应用程序代码中。

这些例程可能会尝试转换结果的数据类型。例如，如果内部表示是 FLOAT 并且请求文本结果，则在内部使用sqlite3_snprintf()自动执行转换。下表详细说明了应用的转换：

Internal
Type 		Requested
Type 		Conversion

NULL INTEGER Result is 0
NULL FLOAT Result is 0.0
NULL TEXT Result is a NULL pointer
NULL BLOB Result is a NULL pointer
INTEGER FLOAT Convert from integer to float
INTEGER TEXT ASCII rendering of the integer
INTEGER BLOB Same as INTEGER->TEXT
FLOAT INTEGER CAST to INTEGER
FLOAT TEXT ASCII rendering of the float
FLOAT BLOB CAST to BLOB
TEXT INTEGER CAST to INTEGER
TEXT FLOAT CAST to REAL
TEXT BLOB No change
BLOB INTEGER CAST to INTEGER
BLOB FLOAT CAST to REAL
BLOB TEXT CAST to TEXT, ensure zero terminator

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

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

最安全的策略是以下列方式之一调用这些例程：

换句话说，您应该首先调用 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()。

只要输入参数正确，这些例程只有在格式转换期间发生内存不足错误时才会失败。只有以下接口子集会出现内存不足错误：

如果发生内存不足错误，则这些例程的返回值与该列包含 SQL NULL 值一样。有效的 SQL NULL 返回可以与内存不足错误区分开来，方法是在获得可疑返回值之后和在同一数据库连接上调用任何其他 SQLite 接口之前立即调用sqlite3_errcode()。

另请参阅 对象、 常量和 函数的列表。