NAME
sqlite3_create_collation,
sqlite3_create_collation_v2,
sqlite3_create_collation16 —
Define
New Collating Sequences
SYNOPSIS
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*) );
DESCRIPTION
These functions add, remove, or modify a collation associated with the database
connection specified as the first argument.
The name of the collation is a UTF-8 string for sqlite3_create_collation() and
sqlite3_create_collation_v2() and a UTF-16 string in native byte order for
sqlite3_create_collation16(). Collation names that compare equal according to
sqlite3_strnicmp() are considered to be the same name.
The third argument (eTextRep) must be one of the constants:
- SQLITE_UTF8,
- SQLITE_UTF16LE,
- SQLITE_UTF16BE,
- SQLITE_UTF16, or
- SQLITE_UTF16_ALIGNED.
The eTextRep argument determines the encoding of strings passed to the collating
function callback, xCallback. The SQLITE_UTF16 and SQLITE_UTF16_ALIGNED values
for eTextRep force strings to be UTF16 with native byte order. The
SQLITE_UTF16_ALIGNED value for eTextRep forces strings to begin on an even
byte address.
The fourth argument, pArg, is an application data pointer that is passed through
as the first argument to the collating function callback.
The fifth argument, xCallback, is a pointer to the collating function. Multiple
collating functions can be registered using the same name but with different
eTextRep parameters and SQLite will use whichever function requires the least
amount of data transformation. If the xCallback argument is NULL then the
collating function is deleted. When all collating functions having the same
name are deleted, that collation is no longer usable.
The collating function callback is invoked with a copy of the pArg application
data pointer and with two strings in the encoding specified by the eTextRep
argument. The collating function must return an integer that is negative,
zero, or positive if the first string is less than, equal to, or greater than
the second, respectively. A collating function must always return the same
answer given the same inputs. If two or more collating functions are
registered to the same collation name (using different eTextRep values) then
all must give an equivalent answer when invoked with equivalent strings. The
collating function must obey the following properties for all strings A, B,
and C:
- If A==B then B==A.
- If A==B and B==C then A==C.
- If A<B THEN B>A.
- If A<B and B<C then A<C.
If a collating function fails any of the above constraints and that collating
function is registered and used, then the behavior of SQLite is undefined.
The sqlite3_create_collation_v2() works like sqlite3_create_collation() with the
addition that the xDestroy callback is invoked on pArg when the collating
function is deleted. Collating functions are deleted when they are overridden
by later calls to the collation creation functions or when the database
connection is closed using sqlite3_close().
The xDestroy callback is <u>not</u> called if the
sqlite3_create_collation_v2() function fails. Applications that invoke
sqlite3_create_collation_v2() with a non-NULL xDestroy argument should check
the return code and dispose of the application data pointer themselves rather
than expecting SQLite to deal with it for them. This is different from every
other SQLite interface. The inconsistency is unfortunate but cannot be changed
without breaking backwards compatibility.
SEE ALSO
sqlite3(3),
sqlite3_close(3),
sqlite3_collation_needed(3),
sqlite3_stricmp(3),
SQLITE_UTF8(3)