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_collation() 和 sqlite3_create_collation_v2() ，排序规则的名称是 UTF-8 字符串，对于 sqlite3_create_collation16() ，规则为本机字节顺序的 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_collation_v2() 的工作原理类似于 sqlite3_create_collation() ，并且在删除整理函数时，在 pArg 上调用 xDestroy 回调函数。如果稍后调用排序规则创建函数或使用 sqlite3_close() 关闭数据库连接时，它们将被覆盖函数删除。
如果 sqlite3_create_collation_v2() 函数失败，则不会调用 xDestroy 回调。使用非 NULL xDestroy 参数调用 sqlite3_create_collation_v2() 的应用程序应检查返回代码并自行处理应用程序数据指针，而不是期望 SQLite 为它们处理它。这与其他 SQLite 接口不同。这种不一致是不幸的，但如果不打破向后兼容性就不能改变。
另请参见：sqlite3_collation_needed() 和 sqlite3_collation_needed16() 。
另请参见对象，常量和函数的列表。
SQLite is in the Public Domain.本文档系腾讯云开发者社区成员共同维护，如有问题请联系 cloudcommunity@tencent.com
