From: drh Date: Fri, 17 Sep 2010 19:45:20 +0000 (+0000) Subject: Updates to the documentation for sqlite3_create_collation(). X-Git-Tag: experimental~16 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=17cbfae98c6640a257b448a6a5ad191278a85a4c;p=thirdparty%2Fsqlite.git Updates to the documentation for sqlite3_create_collation(). FossilOrigin-Name: 3df7715a7736867db34195aa8d98ba2e6f2f0b19 --- diff --git a/manifest b/manifest index 9fda6ace65..3427ade890 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,8 @@ -C Add\stests\sfor\ssome\ssyntax\sdiagrams\sin\slang_select.html. -D 2010-09-17T19:04:19 +-----BEGIN PGP SIGNED MESSAGE----- +Hash: SHA1 + +C Updates\sto\sthe\sdocumentation\sfor\ssqlite3_create_collation(). +D 2010-09-17T19:45:21 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f F Makefile.in c599a15d268b1db2aeadea19df2adc3bf2eb6bee F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23 @@ -174,7 +177,7 @@ F src/resolve.c 1c0f32b64f8e3f555fe1f732f9d6f501a7f05706 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697 F src/select.c b0b124781474e4e0c8f64022875e5e2009e13443 F src/shell.c 8517fc1f9c59ae4007e6cc8b9af91ab231ea2056 -F src/sqlite.h.in f344686426dadb264bbf66ba1b31625e4086871d +F src/sqlite.h.in 2f2eaf294f6ee8a4af855124478d4f9e6d5aa24e F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89 F src/sqliteInt.h ef7ed8746759c09edd87e5550de973a4da3e4ca7 F src/sqliteLimit.h a17dcd3fb775d63b64a43a55c54cb282f9726f44 @@ -858,7 +861,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f -P ee52589c80a6d37dc8c7a86a0e3b531ec4dd8d45 -R 31c4b270de35f676fcc4204cc88bacd6 -U dan -Z 0f88d4009af295c3a193758a524f6f37 +P 2254e93bd5f70af5d3b2021983e4b826e601ee8f +R 68b354da71b9d657f6ac68c58c74ceab +U drh +Z 6e7a6eda418f1d79951195cf015cfb56 +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v1.4.6 (GNU/Linux) + +iD8DBQFMk8VWoxKgR168RlERAg7eAJoCg5OlQpLAVvd2mAGXIMxyKruurgCfdbHR +DOUZfuTIL/auG1NIwilR3cg= +=lDa/ +-----END PGP SIGNATURE----- diff --git a/manifest.uuid b/manifest.uuid index 20daacde43..52efe73f8a 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -2254e93bd5f70af5d3b2021983e4b826e601ee8f \ No newline at end of file +3df7715a7736867db34195aa8d98ba2e6f2f0b19 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index cf0424657b..7944a0d603 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -3759,46 +3759,70 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n); /* ** CAPI3REF: Define New Collating Sequences ** -** These functions are used to add new collation sequences to the -** [database connection] specified as the first argument. +** ^These functions add, remove, or modify a [collation] associated +** with the [database connection] specified as the first argument. ** -** ^The name of the new collation sequence is specified as a UTF-8 string +** ^The name of the collation is 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] to indicate that the routine -** expects pointers to be UTF-16 strings in the native byte order, or the -** argument can be [SQLITE_UTF16_ALIGNED] if the -** the routine expects pointers to 16-bit word aligned strings -** of UTF-16 in the native byte order. -** -** 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 any more). -** ^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). +** 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: +** )^ +** ^The eTextRep argument determines the encoding of strings passed +** to the collating function callback, xCallback. +** ^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 a application data pointer that is passed +** through as the first argument to the collating function callback. +** +** ^The fifth argument, xCallback, 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 xCallback 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 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 alway 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() -** 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()]. +** 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()]. ** ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. */ @@ -3806,14 +3830,14 @@ int sqlite3_create_collation( sqlite3*, const char *zName, int eTextRep, - void*, + void *pArg, int(*xCompare)(void*,int,const void*,int,const void*) ); int sqlite3_create_collation_v2( sqlite3*, const char *zName, int eTextRep, - void*, + void *pArg, int(*xCompare)(void*,int,const void*,int,const void*), void(*xDestroy)(void*) ); @@ -3821,7 +3845,7 @@ int sqlite3_create_collation16( sqlite3*, const void *zName, int eTextRep, - void*, + void *pArg, int(*xCompare)(void*,int,const void*,int,const void*) );