Определение новых правил сортировки

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*)
);

Эти функции добавляют, удаляют или изменяют правила сортировки, связанные с соединением с базой данных, указанным в качестве первого аргумента.

Имя правила сортировки представляет собой строку UTF-8 для sqlite3_create_collation() и sqlite3_create_collation_v2() и строку UTF-16 в родном байтовом порядке для sqlite3_create_collation16(). Имена правил сортировки, сравниваемые как равные в соответствии с sqlite3_strnicmp(), считаются одинаковыми.

Третий аргумент (eTextRep) должен быть одним из констант:

• SQLITE_UTF8,
• SQLITE_UTF16LE,
• SQLITE_UTF16BE,
• SQLITE_UTF16, или
• 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(), с добавлением того, что обратный вызов xDestroy вызывается для pArg, когда функция сортировки удаляется. Функции сортировки удаляются при перезаписи их более поздними вызовами функций создания правил сортировки или при закрытии соединения с базой данных с помощью sqlite3_close().

Обратный вызов xDestroy не вызывается, если функция sqlite3_create_collation_v2() завершается неудачей. Приложения, которые вызывают sqlite3_create_collation_v2() с ненулевым аргументом xDestroy, должны проверять код возврата и сами освобождать указатель на данные приложения, а не ожидать, что SQLite это сделает за них. Это отличается от всех других интерфейсов SQLite. Несоответствие неудачное, но его нельзя изменить без нарушения обратной совместимости.

См. также: sqlite3_collation_needed() и sqlite3_collation_needed16().

См. также списки объектов, констант и функций.