Create Or Redefine SQL Functions

Create Or Redefine SQL Functions

int sqlite3_create_function(
  sqlite3 *db,
  const char *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)

int sqlite3_create_function16(
  sqlite3 *db,
  const void *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)

int sqlite3_create_function_v2(
  sqlite3 *db,
  const char *zFunctionName,
  int nArg,
  int eTextRep,
  void *pApp,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*),
  void(*xDestroy)(void*)

这些函数（统称为“函数创建例程”）用于添加 SQL 函数或聚合或重新定义现有 SQL 函数或聚合的行为。这些例程之间的唯一区别是第二个参数（要创建的函数的名称）的文本编码以及应用程序数据指针的析构函数回调的存在或不存在。

第一个参数是要添加 SQL 函数的数据库连接。如果应用程序使用多个数据库连接，则必须将应用程序定义的 SQL 函数分别添加到每个数据库连接。

第二个参数是要创建或重新定义的 SQL 函数的名称。在 UTF-8 表示中，名称的长度限制为255个字节，不包括零终结符。请注意，名称长度限制为 UTF-8 字节，而不是字符或 UTF-16 字节。任何尝试创建名称较长的函数都会导致返回 SQLITE_MISUSE 。

第三个参数（nArg）是 SQL 函数或聚合参数的个数。如果此参数为-1，那么 SQL 函数或聚合可以采用介于0和由 sqlite3_limit（ SQLITE_LIMIT_FUNCTION_ARG ）设置的限制之间的任意数量的参数。如果第三个参数小于-1或大于127，则行为是未定义的。

第四个参数，eTextRep 指定了此 SQL 函数对其参数所喜欢的文本进行编码。如果函数实现在输入上调用 sqlite3_value_text16le() ，或者 SQLITE_UTF16BE（如果实现在输入上调用 sqlite3_value_text16be() ，或者 SQLITE_UTF16（如果使用 sqlite3_value_text16() ），则该应用程序应该将此参数设置为 SQLITE_UTF16LE ；否则为 SQLITE_UTF8 。同一个 SQL 函数可以使用不同的首选文本编码进行多次注册，每种编码都有不同的实现。当同一个函数的多个实现可用时，SQLite 将选择一个涉及最少数据转换的实现。

第四个参数可以选择性地与 SQLITE_DETERMINISTIC 进行或运算，以表示在单个 SQL 语句中给定相同输入的情况下，函数将始终返回相同的结果。大多数 SQL 函数都是确定性的。内置的 random() SQL 函数是一个非确定性函数的例子。SQLite 查询规划器能够对确定性函数执行额外的优化，因此建议尽可能使用 SQLITE_DETERMINISTIC 标志。

第五个参数是一个任意指针。该函数的实现可以使用 sqlite3_user_data() 访问此指针。

第六，第七和第八个参数， xFunc ，xStep 和 xFinal 是指向实现 SQL 函数或聚合的 C 语言函数的指针。标量 SQL 函数仅需要实现 xFunc 回调; NULL 指针必须作为 xStep 和 xFinal 参数传递。集合 SQL 函数需要 xStep 的实现，并且必须为 xFunc 传递 xFinal 和 NULL 指针。要删除现有的 SQL 函数或聚合，请为所有三个函数回调传递 NULL 指针。

如果 sqlite3_create_function_v2() 的第九个参数不是 NULL ，那么它是应用程序数据指针的析构函数。当函数被删除时，通过重载或数据库连接关闭时，调用析构函数。如果调用 sqlite3_create_function_v2() 失败，也会调用析构函数。调用第十个参数的析构函数回调时，会传递一个参数，该参数是应用程序数据指针的副本，它是 sqlite3_create_function_v2() 的第五个参数。

允许注册具有相同名称的相同函数的多个实现，但具有不同数量的参数或不同的优选文本编码。SQLite 将使用与 SQL 函数使用方式最为匹配的实现。具有非负 nArg 参数的函数实现比具有负 nArg 的函数实现更好匹配。首选文本编码与数据库编码相匹配的功能比编码不同的功能更好。编码差异在 UTF16le 和 UTF16be 之间的函数比编码差异在 UTF8 和 UTF16 之间的函数更接近匹配。

内置函数可能会被新的应用程序定义的函数重载。

允许应用程序定义的函数调用其他 SQLite 接口。但是，这些调用不能关闭数据库连接，也不能最终确定或重置运行该函数的预准备语句。

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

 SQLite is in the Public Domain.