1.Dd January 24, 2024 2.Dt SQLITE3_CREATE_COLLATION 3 3.Os 4.Sh NAME 5.Nm sqlite3_create_collation , 6.Nm sqlite3_create_collation_v2 , 7.Nm sqlite3_create_collation16 8.Nd define new collating sequences 9.Sh SYNOPSIS 10.In sqlite3.h 11.Ft int 12.Fo sqlite3_create_collation 13.Fa "sqlite3*" 14.Fa "const char *zName" 15.Fa "int eTextRep" 16.Fa "void *pArg" 17.Fa "int(*xCompare)(void*,int,const void*,int,const void*)" 18.Fc 19.Ft int 20.Fo sqlite3_create_collation_v2 21.Fa "sqlite3*" 22.Fa "const char *zName" 23.Fa "int eTextRep" 24.Fa "void *pArg" 25.Fa "int(*xCompare)(void*,int,const void*,int,const void*)" 26.Fa "void(*xDestroy)(void*)" 27.Fc 28.Ft int 29.Fo sqlite3_create_collation16 30.Fa "sqlite3*" 31.Fa "const void *zName" 32.Fa "int eTextRep" 33.Fa "void *pArg" 34.Fa "int(*xCompare)(void*,int,const void*,int,const void*)" 35.Fc 36.Sh DESCRIPTION 37These functions add, remove, or modify a collation associated 38with the database connection specified as the first 39argument. 40.Pp 41The name of the collation is a UTF-8 string for sqlite3_create_collation() 42and sqlite3_create_collation_v2() and a UTF-16 string in native byte 43order for sqlite3_create_collation16(). 44Collation names that compare equal according to 45.Fn sqlite3_strnicmp 46are considered to be the same name. 47.Pp 48The third argument (eTextRep) must be one of the constants: 49.Bl -bullet 50.It 51SQLITE_UTF8, 52.It 53SQLITE_UTF16LE, 54.It 55SQLITE_UTF16BE, 56.It 57SQLITE_UTF16, or 58.It 59SQLITE_UTF16_ALIGNED. 60.El 61.Pp 62The eTextRep argument determines the encoding of strings passed to 63the collating function callback, xCompare. 64The SQLITE_UTF16 and SQLITE_UTF16_ALIGNED 65values for eTextRep force strings to be UTF16 with native byte order. 66The SQLITE_UTF16_ALIGNED value for eTextRep forces 67strings to begin on an even byte address. 68.Pp 69The fourth argument, pArg, is an application data pointer that is passed 70through as the first argument to the collating function callback. 71.Pp 72The fifth argument, xCompare, is a pointer to the collating function. 73Multiple collating functions can be registered using the same name 74but with different eTextRep parameters and SQLite will use whichever 75function requires the least amount of data transformation. 76If the xCompare argument is NULL then the collating function is deleted. 77When all collating functions having the same name are deleted, that 78collation is no longer usable. 79.Pp 80The collating function callback is invoked with a copy of the pArg 81application data pointer and with two strings in the encoding specified 82by the eTextRep argument. 83The two integer parameters to the collating function callback are the 84length of the two strings, in bytes. 85The collating function must return an integer that is negative, zero, 86or positive if the first string is less than, equal to, or greater 87than the second, respectively. 88A collating function must always return the same answer given the same 89inputs. 90If two or more collating functions are registered to the same collation 91name (using different eTextRep values) then all must give an equivalent 92answer when invoked with equivalent strings. 93The collating function must obey the following properties for all strings 94A, B, and C: 95.Bl -enum 96.It 97If A==B then B==A. 98.It 99If A==B and B==C then A==C. 100.It 101If A<B THEN B>A. 102.It 103If A<B and B<C then A<C. 104.El 105.Pp 106If a collating function fails any of the above constraints and that 107collating function is registered and used, then the behavior of SQLite 108is undefined. 109.Pp 110The sqlite3_create_collation_v2() works like sqlite3_create_collation() 111with the addition that the xDestroy callback is invoked on pArg when 112the collating function is deleted. 113Collating functions are deleted when they are overridden by later calls 114to the collation creation functions or when the database connection 115is closed using 116.Fn sqlite3_close . 117The xDestroy callback is \fInot\fP called if the sqlite3_create_collation_v2() 118function fails. 119Applications that invoke sqlite3_create_collation_v2() with a non-NULL 120xDestroy argument should check the return code and dispose of the application 121data pointer themselves rather than expecting SQLite to deal with it 122for them. 123This is different from every other SQLite interface. 124The inconsistency is unfortunate but cannot be changed without breaking 125backwards compatibility. 126.Pp 127.Sh IMPLEMENTATION NOTES 128These declarations were extracted from the 129interface documentation at line 6246. 130.Bd -literal 131SQLITE_API int sqlite3_create_collation( 132 sqlite3*, 133 const char *zName, 134 int eTextRep, 135 void *pArg, 136 int(*xCompare)(void*,int,const void*,int,const void*) 137); 138SQLITE_API int sqlite3_create_collation_v2( 139 sqlite3*, 140 const char *zName, 141 int eTextRep, 142 void *pArg, 143 int(*xCompare)(void*,int,const void*,int,const void*), 144 void(*xDestroy)(void*) 145); 146SQLITE_API int sqlite3_create_collation16( 147 sqlite3*, 148 const void *zName, 149 int eTextRep, 150 void *pArg, 151 int(*xCompare)(void*,int,const void*,int,const void*) 152); 153.Ed 154.Sh SEE ALSO 155.Xr sqlite3 3 , 156.Xr sqlite3_close 3 , 157.Xr sqlite3_collation_needed 3 , 158.Xr sqlite3_stricmp 3 , 159.Xr SQLITE_UTF8 3 160