Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

SQLITE3_CREATE_COLLATION(3)                           Library Functions Manual

NAME
     sqlite3_create_collation, sqlite3_create_collation_v2,
     sqlite3_create_collation16 - define new collating sequences

SYNOPSIS
     #include <sqlite3.h>

     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, xCompare.  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, xCompare, 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 xCompare
     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 two integer parameters to the collating
     function callback are the length of the two strings, in bytes.  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:

     1.   If A==B then B==A.

     2.   If A==B and B==C then A==C.

     3.   If A<B THEN B>A.

     4.   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 not 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.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 6142.

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

SEE ALSO
     sqlite3(3), sqlite3_close(3), sqlite3_collation_needed(3),
     sqlite3_stricmp(3), SQLITE_UTF8(3)

NetBSD 10.99                    August 24, 2023                   NetBSD 10.99