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 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_ALIGNED to indicate that the routine expects pointers to 16-bit word aligned strings of UTF-16 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 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().

Invariants:

H16603 A successful call to the sqlite3_create_collation_v2(B,X,E,P,F,D) interface registers function F as the comparison function used to implement collation X on the database connection B for databases having encoding E.
H16604 SQLite understands the X parameter to sqlite3_create_collation_v2(B,X,E,P,F,D) as a zero-terminated UTF-8 string in which case is ignored for ASCII characters and is significant for non-ASCII characters.
H16606 Successive calls to sqlite3_create_collation_v2(B,X,E,P,F,D) with the same values for B, X, and E, override prior values of P, F, and D.
H16609 If the destructor D in sqlite3_create_collation_v2(B,X,E,P,F,D) is not NULL then it is called with argument P when the collating function is dropped by SQLite.
H16612 A collating function is dropped when it is overloaded.
H16615 A collating function is dropped when the database connection is closed using sqlite3_close().
H16618 The pointer P in sqlite3_create_collation_v2(B,X,E,P,F,D) is passed through as the first parameter to the comparison function F for all subsequent invocations of F.
H16621 A call to sqlite3_create_collation(B,X,E,P,F) is exactly the same as a call to sqlite3_create_collation_v2() with the same parameters and a NULL destructor.
H16624 Following a sqlite3_create_collation_v2(B,X,E,P,F,D), SQLite uses the comparison function F for all text comparison operations on the database connection B on text values that use the collating sequence named X.
H16627 The sqlite3_create_collation16(B,X,E,P,F) works the same as sqlite3_create_collation(B,X,E,P,F) except that the collation name X is understood as UTF-16 in native byte order instead of UTF-8.
H16630 When multiple comparison functions are available for the same collating sequence, SQLite chooses the one whose text encoding requires the least amount of conversion from the default text encoding of the database.

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC