Define New Collating Sequences

Define New Collating Sequences

int sqlite3_create_collation(
  sqlite3*, 
  const char *zName, 
  int eTextRep, 
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)

int sqlite3_create_collation_v2(
  sqlite3*, 
  const char *zName, 
  int eTextRep, 
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*),
  void(*xDestroy)(void*)

int sqlite3_create_collation16(
  sqlite3*, 
  const void *zName,
  int eTextRep, 
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)

这些函数添加，删除或修改与指定为第一个参数的数据库连接关联的排序规则。

对于 sqlite3_create_collat​​ion() 和 sqlite3_create_collat​​ion_v2() ，排序规则的名称是 UTF-8 字符串，对于 sqlite3_create_collat​​ion16() ，规则为本机字节顺序的 UTF-16 字符串。根据 sqlite3_strnicmp() 比较相等的整理名称被认为是相同的名称。

第三个参数（eTextRep）必须是常量之一：

• SQLITE_UTF8,

• SQLITE_UTF16LE,

• SQLITE_UTF16BE,

• SQLITE_UTF16, 或

• SQLITE_UTF16_ALIGNED.

eTextRep 参数确定传递给整理函数回调函数 xCallback 的字符串的编码。eTextRep 的 SQLITE_UTF16 和 SQLITE_UTF16_ALIGNED 值强制字符串为本机字节顺序的 UTF16 。eTextRep 的 SQLITE_UTF16_ALIGNED 值强制字符串从偶数字节地址开始。

第四个参数 pArg 是作为第一个参数传递给整理函数回调函数的应用程序数据指针。

第五个参数 xCallback 是一个指向整理函数的指针。可以使用相同的名称注册多个整理函数，但使用不同的 eTextRep 参数，并且 SQLite 将使用哪个函数需要最少量的数据转换。如果 xCallback 参数为 NULL ，则会删除整理函数。当具有相同名称的所有比较功能被删除时，该比较不再可用。

使用 pArg 应用程序数据指针的副本和 eTextRep 参数指定的编码中的两个字符串调用整理函数回调。如果第一个字符串分别小于，等于或大于第二个字符串，则整理函数必须返回负值，零或正值的整数。给定相同的输入时，整理函数必须始终返回相同的答案。如果两个或多个整理函数注册到相同的排序规则名称（使用不同的 eTextRep 值），则所有规则都必须在用等效字符串调用时给出等效的答案。整理函数必须遵守所有字符串 A ，B 和 C 的以下属性：

1. If A==B then B==A.

2. If A==B and B==C then A==C.

3. If A<B THEN B>A.

4. If A<B and B<C then A<C.

如果一个整理函数没有通过上述任何约束，并且已经注册并使用了整理函数，那么 SQLite 的行为是未定义的。

sqlite3_create_collat​​ion_v2() 的工作原理类似于 sqlite3_create_collat​​ion() ，并且在删除整理函数时，在 pArg 上调用 xDestroy 回调函数。如果稍后调用排序规则创建函数或使用 sqlite3_close() 关闭数据库连接时，它们将被覆盖函数删除。

如果 sqlite3_create_collat​​ion_v2() 函数失败，则不会调用 xDestroy 回调。使用非 NULL xDestroy 参数调用 sqlite3_create_collat​​ion_v2() 的应用程序应检查返回代码并自行处理应用程序数据指针，而不是期望 SQLite 为它们处理它。这与其他 SQLite 接口不同。这种不一致是不幸的，但如果不打破向后兼容性就不能改变。

另请参见：sqlite3_collat​​ion_needed() 和 sqlite3_collat​​ion_needed16() 。

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

 SQLite is in the Public Domain.