SQLite C 接口
获取 SQL 值
const void *sqlite3_value_blob(sqlite3_value*); double sqlite3_value_double(sqlite3_value*); int sqlite3_value_int(sqlite3_value*); sqlite3_int64 sqlite3_value_int64(sqlite3_value*); void *sqlite3_value_pointer(sqlite3_value*, const char*); const unsigned char *sqlite3_value_text(sqlite3_value*); const void *sqlite3_value_text16(sqlite3_value*); const void *sqlite3_value_text16le(sqlite3_value*); const void *sqlite3_value_text16be(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); int sqlite3_value_bytes16(sqlite3_value*); int sqlite3_value_type(sqlite3_value*); int sqlite3_value_numeric_type(sqlite3_value*); int sqlite3_value_nochange(sqlite3_value*); int sqlite3_value_frombind(sqlite3_value*);
概括:
sqlite3_value_blob → BLOB value sqlite3_value_double → REAL value sqlite3_value_int → 32-bit INTEGER value sqlite3_value_int64 → 64-bit INTEGER value sqlite3_value_pointer → Pointer value sqlite3_value_text → UTF-8 TEXT value sqlite3_value_text16 → UTF-16 TEXT value in the native byteorder sqlite3_value_text16be → UTF-16be TEXT value sqlite3_value_text16le → UTF-16le TEXT value sqlite3_value_bytes → Size of a BLOB or a UTF-8 TEXT in bytes sqlite3_value_bytes16 → Size of UTF-16 TEXT in bytes sqlite3_value_type → Default datatype of the value sqlite3_value_numeric_type → Best numeric datatype of the value sqlite3_value_nochange → True if the column is unchanged in an UPDATE against a virtual table. sqlite3_value_frombind → True if value originated from a bound parameter
细节:
这些例程从受保护的 sqlite3_value对象中提取类型、大小和内容信息 。受保护的 sqlite3_value 对象用于将参数信息传递到实现应用程序定义的 SQL 函数和虚拟表的函数中。
这些例程仅适用于受保护的 sqlite3_value对象。任何在未受保护的 sqlite3_value上使用这些例程的尝试 都不是线程安全的。
这些例程就像相应的列访问函数一样工作, 除了这些例程采用单个受保护的 sqlite3_value对象指针而不是sqlite3_stmt*指针和整数列号。
sqlite3_value_text16() 接口以主机的本机字节顺序提取 UTF-16 字符串。sqlite3_value_text16be() 和 sqlite3_value_text16le() 接口分别将 UTF-16 字符串提取为大端和小端。
如果sqlite3_value对象 V 是使用sqlite3_bind_pointer(S,I,P,X,D)或sqlite3_result_pointer(C,P,X,D)初始化的, 并且如果 X 和 Y 是根据 strcmp(X,Y) 比较相等的字符串,则sqlite3_value_pointer(V,Y) 将返回指针 P。否则,sqlite3_value_pointer(V,Y) 返回 NULL。sqlite3_bind_pointer() 例程是为 SQLite 3.20.0 添加的指针传递接口的一部分。
sqlite3_value_type(V) 接口返回 sqlite3_value对象 V的初始数据类型的 数据类型代码。返回值是SQLITE_INTEGER、 SQLITE_FLOAT、SQLITE_TEXT、SQLITE_BLOB或SQLITE_NULL 之一。其他接口可能会更改 sqlite3_value 对象的数据类型。例如,如果数据类型最初是 SQLITE_INTEGER 并且调用 sqlite3_value_text(V) 来提取该整数的文本值,那么对 sqlite3_value_type(V) 的后续调用可能会返回 SQLITE_TEXT。是否发生持久性内部数据类型转换是未定义的,可能会从一个 SQLite 版本到下一个版本发生变化。
sqlite3_value_numeric_type() 接口尝试对值应用数字关联。这意味着尝试将值转换为整数或浮点数。如果可以在不丢失信息的情况下进行此类转换(换句话说,如果该值是一个看起来像数字的字符串),则执行转换。否则不会发生转换。返回转换后的数据类型。
在虚拟表的xUpdate方法中,sqlite3_value_nochange(X) 接口返回 true 当且仅当与 X 对应的列未被调用 xUpdate 方法调用以实现的 UPDATE 操作更改,并且如果和先前的xColumn方法调用被调用以提取未设置结果而返回的该列的值(可能是因为它查询了sqlite3_vtab_nochange()并发现该列未更改)。在xUpdate方法中,sqlite3_value_nochange(X) 为真的任何值在所有其他方面都将显示为 NULL 值。如果在xUpdate以外的任何地方调用 sqlite3_value_nochange(X)方法调用 UPDATE 语句,则返回值是任意且无意义的。
如果值 X 源自sqlite3_bind()接口之一,则 sqlite3_value_frombind(X) 接口返回非零 。如果 X 来自 SQL 文字值、表列或表达式,则 sqlite3_value_frombind(X) 返回零。
请特别注意,从 sqlite3_value_blob() 、 sqlite3_value_text() 或 sqlite3_value_text16() 返回的指针可能会因随后 调用 sqlite3_value_bytes()、sqlite3_value_bytes16()、sqlite3_value_text()或sqlite3_value_text16 ()而失效。
这些例程必须从与提供sqlite3_value*参数的 SQL 函数相同的线程中调用。
只要输入参数正确,这些例程只有在格式转换期间发生内存不足错误时才会失败。只有以下接口子集会出现内存不足错误:
- sqlite3_value_blob()
- sqlite3_value_text()
- sqlite3_value_text16()
- sqlite3_value_text16le()
- sqlite3_value_text16be()
- sqlite3_value_bytes()
- sqlite3_value_bytes16()
如果发生内存不足错误,则这些例程的返回值与该列包含 SQL NULL 值一样。有效的 SQL NULL 返回可以与内存不足错误区分开来,方法是在获得可疑返回值之后和在同一数据库连接上调用任何其他 SQLite 接口之前立即调用sqlite3_errcode()。