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