Определите новые последовательности сопоставления

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() с не-NULL xDestroy, должны проверить код возврата и избавиться от указателя данных приложения сами вместо того, чтобы ожидать, что SQLite будет иметь дело с ним. Это отличается от любого интерфейса SQLite. Несоответствие неудачно, но не может быть изменено, не ломая обратную совместимость.

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