小巧。快速。可靠。
三选二。

SQLite C 接口

定义新的排序规则

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_collation() 和 sqlite3_create_collation_v2() 是一个 UTF-8 字符串，对于 sqlite3_create_collation16() 是一个以本地字节顺序存储的 UTF-16 字符串。根据sqlite3_strnicmp()比较相等的排序规则名称被视为相同的名称。

第三个参数 (eTextRep) 必须是以下常量之一：

eTextRep 参数确定传递给排序函数回调 xCompare 的字符串的编码。SQLITE_UTF16 和 SQLITE_UTF16_ALIGNED 的 eTextRep 值强制字符串为使用本地字节顺序的 UTF16。eTextRep 的 SQLITE_UTF16_ALIGNED 值强制字符串以偶数字节地址开始。

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

第五个参数 xCompare 是指向排序函数的指针。可以使用相同的名称但使用不同的 eTextRep 参数注册多个排序函数，SQLite 将使用需要最少数据转换的函数。如果 xCompare 参数为 NULL，则删除排序函数。当所有具有相同名称的排序函数都被删除时，该排序规则将不再可用。

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

  1. 如果 A==B，则 B==A。
  2. 如果 A==B 且 B==C，则 A==C。
  3. 如果 A<B，则 B>A。
  4. 如果 A<B 且 B<C，则 A<C。

如果排序函数违反了上述任何约束，并且该排序函数已注册并使用，则 SQLite 的行为未定义。

sqlite3_create_collation_v2() 的工作方式类似于 sqlite3_create_collation()，此外，当删除排序函数时，会对 pArg 调用 xDestroy 回调。当通过对排序规则创建函数的后续调用覆盖排序函数时，或当使用sqlite3_close()关闭数据库连接时，会删除排序函数。

如果 sqlite3_create_collation_v2() 函数失败，则不会调用 xDestroy 回调。调用 sqlite3_create_collation_v2() 并使用非 NULL xDestroy 参数的应用程序应检查返回值并自行处理应用程序数据指针，而不是期望 SQLite 为其处理。这与其他所有 SQLite 接口都不一致。这种不一致令人遗憾，但无法在不破坏向后兼容性的情况下进行更改。

另请参阅：sqlite3_collation_needed() 和 sqlite3_collation_needed16()。

另请参阅对象、常量和函数列表。