SQLite的扩展函数Carray()表值函数(三十八)

返回：SQLite—系列文章目录

上一篇:SQLite如何处理CSV 虚拟表

1. 概述

Carray()是一个具有单列的表值函数(名为 “value”)和零行或多行。 carray() 中每一行的“值”取自 C 语言数组由应用程序通过参数绑定提供。这样，carray()函数提供了一种方便的机制来将 C 语言数组绑定到 SQL 查询。

2. 可用性

默认情况下，carray()函数不会编译为 SQLite。它可作为 ext/misc/carray.c 源文件中的可加载扩展名使用。

carray()函数在 3.14 版中首次添加到 SQLite 中(2016-08-08). sqlite3_carray_bind() 接口和在 SQLite 版本 3.34.0 中添加了 carray()的单参数变体(2020-12-01). 在 SQLite 版本 3.41.0 中添加了绑定被解释为 BLOB 的 struct iovec 对象数组的功能 (2023-02-21).

3. 详情

carray()函数接受一个、两个或三个参数。

对于 carray()的 2 个和 3 个参数版本，第一个参数是指向数组的指针。由于指针值不能直接在 SQL 中指定，第一个参数必须是使用 sqlite3_bind_pointer()接口绑定到指针值使用指针类型“Carray”。第二个参数是数组中的元素数。可选的第三个参数是确定元素数据类型的字符串在 C 语言数组中。第三个参数允许的值为：

'int32'
“int64”
“双倍”
'char*'
'struct iovec'

默认数据类型为“int32”。

用于 BLOB 数据的“struct iovec”类型是标准的 Posix 数据结构，通常使用“#include < sys/uio.h>”声明。格式为：

struct iovec {void  *iov_base; /* Starting address */size_t iov_len;  /* Number of bytes to transfer */
};

3.1. 单参数CARRAY

carray()的单参数形式需要特殊的 C 语言名为“sqlite3_carray_bind()”的接口，以便附加值：

  int sqlite3_carray_bind(sqlite3_stmt *pStmt,         /* Statement containing the CARRAY */int idx,                     /* Parameter number for CARRAY argument */void *aData,                 /* Data array */int nData,                   /* Number of entries in the array */int mFlags,                  /* Datatype flag */void (*xDestroy)(void*)      /* Destructor for aData */);

sqlite3_carray_bind（）的 mFlags 参数必须是以下参数之一：

  #define CARRAY_INT32   0#define CARRAY_INT64   1#define CARRAY_DOUBLE  2#define CARRAY_TEXT    3#define CARRAY_BLOB    4

mFlags 参数的高阶位现在必须全部为零，尽管它们可能会在将来的增强功能中使用。的定义指定数据类型和原型的常量 sqlite3_carray_bind()函数在辅助函数中都可用头文件 ext/misc/carray.h。

sqlite3_carray_bind()例程的 xDestroy 参数是一个指针到释放输入数组的函数。SQLite 将调用此函数。xDestroy 参数可以是 “sqlite3.h”：

SQLITE_STATIC → 这意味着调用 sqlite3_carray_bind()维护数据数组的所有权，并且应用程序向 SQLite 承诺它不会更改或解除分配在预处理的语句最终化之前的数据。
SQLITE_TRANSIENT → 此特殊值指示 SQLite 使它自己的数据的私有副本之前 sqlite3_carray_bind()接口返回。

4. 用法

carray()函数可用于查询的 FROM 子句。例如，使用 rowids 从 OBJ 表中查询两个条目取自地址 $PTR 处的 C 语言数组。

SELECT obj.* FROM obj, carray($PTR, 10) AS xWHERE obj.rowid=x.value;

此查询给出相同的结果：

SELECT * FROM obj WHERE rowid IN carray($PTR, 10);

5.例程

以下是一个使用Carray()函数的简单示例：

#include <stdio.h>
#include <sqlite3.h>/* 回调函数 */
static int callback(void * data, int argc, char ** argv, char ** colName) {int i;for (i = 0; i < argc; i++) {printf("%s = %s\n", colName[i], argv[i] ? argv[i] : "NULL");}printf("\n");return 0;
}/* 主函数 */
int main(int argc, char ** argv) {sqlite3 * db;char *errmsg = 0;int ret;char * select = "SELECT * FROM Company;";char * data[10][3];   // 用于存储SQLite的查询结果（Company表）/* 打开SQLite数据库 */ret = sqlite3_open("Test.db", &db);if (ret) {fprintf(stderr, "无法打开数据库：%s\n", sqlite3_errmsg(db));sqlite3_close(db);return 1;}/* 执行SQLite查询语句并将结果存储在已分配的内存空间中 */ret = sqlite3_exec(db, select, callback, data, &errmsg);if (ret != SQLITE_OK) {fprintf(stderr, "SQL语句执行失败：%s\n", errmsg);sqlite3_free(errmsg);sqlite3_close(db);return 1;}/* 打印查询结果 */int i;for(i=0; i<10; i++) {printf("%s %s %s\n", data[i][0], data[i][1], data[i][2]);}/* 关闭SQLite数据库 */sqlite3_close(db);return 0;
}