Small. Fast. Reliable.
Choose any three.

SQLite C接口

定义新的整理顺序

int sqlite3_create_collat​​ion（
  sqlite3 *，
  const char * zName，
  int eTextRep，
  无效* pArg，
  int（* xCompare）（void *，int，常量无效*，int，常量无效*）
）;
int sqlite3_create_collat​​ion_v2（
  sqlite3 *，
  const char * zName，
  int eTextRep，
  无效* pArg，
  int（* xCompare）（void *，int，const void *，int，const void *），
  void（* xDestroy）（void *）
）;
int sqlite3_create_collat​​ion16（
  sqlite3 *，
  const void * zName，
  int eTextRep，
  无效* pArg，
  int（* xCompare）（void *，int，常量无效*，int，常量无效*）
）;

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

排序规则的名称是sqlite3_create_collat​​ion（）和sqlite3_create_collat​​ion_v2（）的UTF-8字符串，以及sqlite3_create_collat​​ion16（）的本机字节顺序的UTF-16字符串。根据sqlite3_strnicmp（）比较相等的排序规则名称被视为相同的名称。

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

eTextRep参数确定传递到整理函数回调xCompare的字符串的编码。该SQLITE_UTF16和SQLITE_UTF16_ALIGNED为eTextRep力的字符串值是UTF-16与本地字节顺序。该SQLITE_UTF16_ALIGNED为eTextRep力的字符串值，开始在偶数字节地址。

第四个参数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 THEN B> A。
  4. 如果A <B且B <C，则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（）。

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