Carray() 表值函数

一、概述

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

2.可用性

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

carray() 函数在 3.14 版（2016-08-08）中首次添加到 SQLite。SQLite 版本 3.34.0 (2020-12-01) 添加了 sqlite3_carray_bind() 接口和 carray() 的单参数变体。

三、细节

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

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

'int32'
'int64'
'double'
'char*'

默认数据类型是“int32”。

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

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 语言数组中获取的 rowid 查询 OBJ 表中的两个条目。

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

此查询给出相同的结果：

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