Result Values From A Query

概要：

细节：

这些例程返回有关查询当前结果行的单个列的信息。在任何情况下，第一个参数都是一个指向正在被评估的准备语句的指针（从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()返回的字符串，即使是空字符串，也始终以零终止。sqlite3_column_blob()对于零长度BLOB的返回值是一个NULL指针。

警告： 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()自动执行转换。下表详细列出了所应用的转换：

InternalType请求的类型转换NULL INTEGER结果为0 NULL FLOAT结果为0.0 NULL TEXT结果为NULL指针NULL BLOB结果为NULL指针INTEGER FLOAT从整数转换为float INTEGER TEXT整数的ASCII呈现INTEGER BLOB与INTEGER-> TEXT相同FLOAT INTEGER CAST到INTEGER FLOAT TEXT FLOAT BLOB CAST到BLOB的ASCII呈现TEXT INTEGER CAST到INTEGER TEXT FLOAT CAST到REAL TEXT BLOB没有改变BLOB INTEGER CAST到INTEGER BLOB FLOAT CAST到REAL BLOB TEXT如果需要添加一个零终止符

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

• 初始内容是一个BLOB，并调用sqlite3_column_text()或sqlite3_column_text16()。可能需要将零终结符添加到字符串中。

• 初始内容是UTF-8文本和sqlite3_column_bytes16()或sqlite3_column_text16()被调用。内容必须转换为UTF-16。

• 初始内容是UTF-16文本和sqlite3_column_bytes()或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_bytes()的sqlite3_column_text16()混合使用。

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

如果在评估任何这些例程时发生内存分配错误，则返回一个默认值。默认值是整数0，浮点数0.0或NULL指针。随后调用sqlite3_errcode()将返回SQLITE_NOMEM。