Small, Fast, Reliable.
Choose any three.

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 char *zName, 
  int eTextRep, 
  void*,
  int(*xCompare)(void*,int,const void*,int,const void*)
);

These functions are used to add new collation sequences to the sqlite3* handle 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_ALIGNED to indicate that the routine expects pointers to 16-bit word aligned strings of UTF16 in the native byte order of the host computer.

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 anymore). Each time the user supplied function is invoked, it is passed a copy of the void* passed as the fourth argument to sqlite3_create_collation() or sqlite3_create_collation16() as its first parameter.

The remaining arguments to the user-supplied routine are two strings, each represented by a length, pair and encoded in the encoding that was passed as the third argument when the collation sequence was registered. The user 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() excapt 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 sqlite3* database handle is closed using sqlite3_close().

The sqlite3_create_collation_v2() interface is experimental and subject to change in future releases. The other collation creation functions are stable.

See also lists of Objects, Constants, and Functions.


This page last modified 2007/11/22 00:41:31 UTC