Small. Fast. Reliable.
Choose any three.

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_blobBLOB结果
sqlite3_column_double真实结果
sqlite3_column_int32位整数结果
sqlite3_column_int6464位INTEGER结果
sqlite3_column_textUTF-8 TEXT结果
sqlite3_column_text16UTF-16 TEXT结果
sqlite3_column_value结果为 不受保护的sqlite3_value对象。
   
sqlite3_column_bytesBLOB或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_INTEGERSQLITE_FLOATSQLITE_TEXTSQLITE_BLOBSQLITE_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()自动执行转换。下表详细介绍了应用的转换:

内部
类型
要求的
类型
转换

空值 整数 结果为0
空值 漂浮 结果是0.0
空值 文本 结果是一个NULL指针
空值 BLOB 结果是一个NULL指针
整数 漂浮 从整数转换为浮点数
整数 文本 整数的ASCII呈现
整数 BLOB 与INTEGER-> TEXT相同
漂浮 整数 转换为整数
漂浮 文本 浮点数的ASCII呈现
漂浮 BLOB 投射到BLOB
文本 整数 转换为整数
文本 漂浮 CAST以REAL
文本 BLOB 没有变化
BLOB 整数 转换为整数
BLOB 漂浮 CAST以REAL
BLOB 文本 如果需要,添加零终止符

请注意,在进行类型转换时,先前调用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值的返回值相同。通过在获得可疑返回值之后并且在同一数据库连接上调用任何其他SQLite接口之前立即调用sqlite3_errcode(),可以将有效的SQL NULL返回与内存不足错误区分开。

另请参见 对象常量函数的列表