Using SQLite

Name

sqlite3_create_collation() — Register a custom collation implementation

Definition

int sqlite3_create_collation(    sqlite3* db, const char* name, int text_rep,
                                 void* udp, comp_func );
int sqlite3_create_collation16(  sqlite3* db, const void* name, int text_rep,
                                 void* udp, comp_func );
int sqlite3_create_collation_v2( sqlite3* db, const char* name, int text_rep,
                                 void* udp, comp_func, dest_func );

int comp_func( void* udp, int sizeA, const void* textA,
                          int sizeB, const void* textB );
void dest_func( void* udp );

db: A database connection.
name: The name of the collation in UTF-8 or UTF-16, depending on the function used.
text_rep: The text representation expected by the comparison function. This value can be one of SQLITE_UTF8, SQLITE_UTF16 (native order), SQLITE_UTF16BE, SQLITE_UTF16LE, or SQLITE_UTF16_ALIGNED (native order, 16-bit aligned).
udp: An application-defined user-data pointer. This value is made available to both the collation comparison function and the collation destroy function.

comp_func: A function pointer to the application-defined custom collation comparison function.
dest_func: An optional function pointer to the application-defined collation destroy function. This may be NULL.
sizeA, sizeB: The length of the textA and textB parameters, respectively, in bytes.
textA, textB: Data buffers containing the text values in the requested representation. These may not be null-terminated.
Returns (sqlite3_create_collation[16][_v2]()): An SQLite result code.
Returns (comp_func()): The results of the comparison. Negative for A < B, zero for A = B, positive for A > B.

Description

These functions define a custom collation implementation. This is done by registering a comparison function under the given collation name and expected text representation.

The only difference between sqlite3_create_collation() and sqlite3_create_collation16() is the text encoding used to define the collation name (the second parameter). The encoding used when calling the comparison function is determined by the third parameter. Either function can be used to register a comparison function that understands any of the given encodings.

The only difference between sqlite3_create_collation() and sqlite3_create_collation_v2() is the addition of the destroy callback function.

A collation name can be overloaded by registering multiple comparison functions under different expected text representations. To delete a collation, register a NULL comparison function pointer under the same collation name and text representation.

The comparison function should return a negative value if testA is less than textB, a zero value if testA and textB are equal, or a positive value if testA is greater than textB. Conceptually, the return value represents A minus B.

The destroy function is called any time a collation is overwritten or when the database connection is shut down. The destroy function will be passed the user-data pointer and given a chance to deallocate any relevant memory. If applicable, a reference to sqlite3_free() can be passed directly to sqlite3_create_collation_v2().

For more information on writing custom collations, see Collation Functions.

Table of Contents for
Using SQLite

Name

Definition

Description

See Also

Table of Contents for Using SQLite

Name

Definition

Description

See Also

Table of Contents for
Using SQLite