1. 概述

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

2. 可用性

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

carray() 函数最早在 SQLite 3.14 版本（2016-08-08）中添加。sqlite3_carray_bind() 接口和 carray() 的单参数变体在 SQLite 3.34.0 版本（2020-12-01）中添加。绑定数组的能力struct iovec解释为 BLOB 的对象是在 SQLite 3.41.0 版本（2023-02-21）中添加的。

3. 细节

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

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

1. 'int32'
2. 'int64'
3. 'double'
4. 'char*'
5. '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() 的单参数形式需要一个名为“sqlite3_carray_bind()”的特殊 C 语言接口才能附加值

  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 子句中使用。例如，要使用位于地址 $PTR 的 C 语言数组中的行 ID 查询 OBJ 表中的两个条目。

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

此查询给出相同的结果

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

本页最后修改时间为 2023-02-17 13:24:09 UTC