Define New Collating Sequences

*** DRAFT ***

SQLite C Interface

Define New Collating Sequences

int sqlite3_create_collation(
  sqlite3*, 
  const char *zName, 
  int eTextRep, 
  void*,
  int(*xCompare)(void*,int,const void*,int,const void*)
);
int sqlite3_create_collation_v2(
  sqlite3*, 
  const char *zName, 
  int eTextRep, 
  void*,
  int(*xCompare)(void*,int,const void*,int,const void*),
  void(*xDestroy)(void*)
);
int sqlite3_create_collation16(
  sqlite3*, 
  const void *zName,
  int eTextRep, 
  void*,
  int(*xCompare)(void*,int,const void*,int,const void*)
);

These functions are used to add new collation sequences to the database connection specified as the first argument.

The name of the new collation sequence is specified as a UTF-8 string for sqlite3_create_collation() and sqlite3_create_collation_v2() and a UTF-16 string for sqlite3_create_collation16(). In all cases the name is passed as the second function argument.

The third argument may be one of the constants SQLITE_UTF8, SQLITE_UTF16LE, or SQLITE_UTF16BE, indicating that the user-supplied routine expects to be passed pointers to strings encoded using UTF-8, UTF-16 little-endian, or UTF-16 big-endian, respectively. The third argument might also be SQLITE_UTF16 to indicate that the routine expects pointers to be UTF-16 strings in the native byte order, or the argument can be SQLITE_UTF16_ALIGNED if the the routine expects pointers to 16-bit word aligned strings of UTF-16 in the native byte order.

A pointer to the user supplied routine must be passed as the fifth argument. If it is NULL, this is the same as deleting the collation sequence (so that SQLite cannot call it any more). Each time the application supplied function is invoked, it is passed as its first parameter a copy of the void* passed as the fourth argument to sqlite3_create_collation() or sqlite3_create_collation16().

The remaining arguments to the application-supplied routine are two strings, each represented by a (length, data) pair and encoded in the encoding that was passed as the third argument when the collation sequence was registered. The application defined collation routine should return negative, zero or positive if the first string is less than, equal to, or greater than the second string. i.e. (STRING1 - STRING2).

The sqlite3_create_collation_v2() works like sqlite3_create_collation() except that it takes an extra argument which is a destructor for the collation. The destructor is called when the collation is destroyed and is passed a copy of the fourth parameter void* pointer of the sqlite3_create_collation_v2(). Collations are destroyed when they are overridden by later calls to the collation creation functions or when the database connection is closed using sqlite3_close().

See also lists of Objects, Constants, and Functions.

*** DRAFT ***