/ Check-in [3df7715a]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates to the documentation for sqlite3_create_collation().
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 3df7715a7736867db34195aa8d98ba2e6f2f0b19
User & Date: drh 2010-09-17 19:45:21
Context
2010-09-17
22:39
Clarifications to the sqlite3_auto_extension() documentation. check-in: ca96e0df user: drh tags: trunk
19:45
Updates to the documentation for sqlite3_create_collation(). check-in: 3df7715a user: drh tags: trunk
19:04
Add tests for some syntax diagrams in lang_select.html. check-in: 2254e93b user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  3755   3755   void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
  3756   3756   void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
  3757   3757   void sqlite3_result_zeroblob(sqlite3_context*, int n);
  3758   3758   
  3759   3759   /*
  3760   3760   ** CAPI3REF: Define New Collating Sequences
  3761   3761   **
  3762         -** These functions are used to add new collation sequences to the
  3763         -** [database connection] specified as the first argument.
         3762  +** ^These functions add, remove, or modify a [collation] associated
         3763  +** with the [database connection] specified as the first argument.
  3764   3764   **
  3765         -** ^The name of the new collation sequence is specified as a UTF-8 string
         3765  +** ^The name of the collation is a UTF-8 string
  3766   3766   ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
  3767         -** and a UTF-16 string for sqlite3_create_collation16(). ^In all cases
  3768         -** the name is passed as the second function argument.
  3769         -**
  3770         -** ^The third argument may be one of the constants [SQLITE_UTF8],
  3771         -** [SQLITE_UTF16LE], or [SQLITE_UTF16BE], indicating that the user-supplied
  3772         -** routine expects to be passed pointers to strings encoded using UTF-8,
  3773         -** UTF-16 little-endian, or UTF-16 big-endian, respectively. ^The
  3774         -** third argument might also be [SQLITE_UTF16] to indicate that the routine
  3775         -** expects pointers to be UTF-16 strings in the native byte order, or the
  3776         -** argument can be [SQLITE_UTF16_ALIGNED] if the
  3777         -** the routine expects pointers to 16-bit word aligned strings
  3778         -** of UTF-16 in the native byte order.
  3779         -**
  3780         -** A pointer to the user supplied routine must be passed as the fifth
  3781         -** argument.  ^If it is NULL, this is the same as deleting the collation
  3782         -** sequence (so that SQLite cannot call it any more).
  3783         -** ^Each time the application supplied function is invoked, it is passed
  3784         -** as its first parameter a copy of the void* passed as the fourth argument
  3785         -** to sqlite3_create_collation() or sqlite3_create_collation16().
  3786         -**
  3787         -** ^The remaining arguments to the application-supplied routine are two strings,
  3788         -** each represented by a (length, data) pair and encoded in the encoding
  3789         -** that was passed as the third argument when the collation sequence was
  3790         -** registered.  The application defined collation routine should
  3791         -** return negative, zero or positive if the first string is less than,
  3792         -** equal to, or greater than the second string. i.e. (STRING1 - STRING2).
         3767  +** and a UTF-16 string in native byte order for sqlite3_create_collation16().
         3768  +** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
         3769  +** considered to be the same name.
         3770  +**
         3771  +** ^(The third argument (eTextRep) must be one of the constants:
         3772  +** <ul>
         3773  +** <li> [SQLITE_UTF8],
         3774  +** <li> [SQLITE_UTF16LE],
         3775  +** <li> [SQLITE_UTF16BE],
         3776  +** <li> [SQLITE_UTF16], or
         3777  +** <li> [SQLITE_UTF16_ALIGNED].
         3778  +** </ul>)^
         3779  +** ^The eTextRep argument determines the encoding of strings passed
         3780  +** to the collating function callback, xCallback.
         3781  +** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
         3782  +** force strings to be UTF16 with native byte order.
         3783  +** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
         3784  +** on an even byte address.
         3785  +**
         3786  +** ^The fourth argument, pArg, is a application data pointer that is passed
         3787  +** through as the first argument to the collating function callback.
         3788  +**
         3789  +** ^The fifth argument, xCallback, is a pointer to the collating function.
         3790  +** ^Multiple collating functions can be registered using the same name but
         3791  +** with different eTextRep parameters and SQLite will use whichever
         3792  +** function requires the least amount of data transformation.
         3793  +** ^If the xCallback argument is NULL then the collating function is
         3794  +** deleted.  ^When all collating functions having the same name are deleted,
         3795  +** that collation is no longer usable.
         3796  +**
         3797  +** ^The collating function callback is invoked with a copy of the pArg 
         3798  +** application data pointer and with two strings in the encoding specified
         3799  +** by the eTextRep argument.  The collating function must return an
         3800  +** integer that is negative, zero, or positive
         3801  +** if the first string is less than, equal to, or greater than the second,
         3802  +** respectively.  A collating function must alway return the same answer
         3803  +** given the same inputs.  If two or more collating functions are registered
         3804  +** to the same collation name (using different eTextRep values) then all
         3805  +** must give an equivalent answer when invoked with equivalent strings.
         3806  +** The collating function must obey the following properties for all
         3807  +** strings A, B, and C:
         3808  +**
         3809  +** <ol>
         3810  +** <li> If A==B then B==A.
         3811  +** <li> If A==B and B==C then A==C.
         3812  +** <li> If A&lt;B THEN B&gt;A.
         3813  +** <li> If A&lt;B and B&lt;C then A&lt;C.
         3814  +** </ol>
         3815  +**
         3816  +** If a collating function fails any of the above constraints and that
         3817  +** collating function is  registered and used, then the behavior of SQLite
         3818  +** is undefined.
  3793   3819   **
  3794   3820   ** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
  3795         -** except that it takes an extra argument which is a destructor for
  3796         -** the collation.  ^The destructor is called when the collation is
  3797         -** destroyed and is passed a copy of the fourth parameter void* pointer
  3798         -** of the sqlite3_create_collation_v2().
  3799         -** ^Collations are destroyed when they are overridden by later calls to the
  3800         -** collation creation functions or when the [database connection] is closed
  3801         -** using [sqlite3_close()].
         3821  +** with the addition that the xDestroy callback is invoked on pArg when
         3822  +** the collating function is deleted.
         3823  +** ^Collating functions are deleted when they are overridden by later
         3824  +** calls to the collation creation functions or when the
         3825  +** [database connection] is closed using [sqlite3_close()].
  3802   3826   **
  3803   3827   ** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
  3804   3828   */
  3805   3829   int sqlite3_create_collation(
  3806   3830     sqlite3*, 
  3807   3831     const char *zName, 
  3808   3832     int eTextRep, 
  3809         -  void*,
         3833  +  void *pArg,
  3810   3834     int(*xCompare)(void*,int,const void*,int,const void*)
  3811   3835   );
  3812   3836   int sqlite3_create_collation_v2(
  3813   3837     sqlite3*, 
  3814   3838     const char *zName, 
  3815   3839     int eTextRep, 
  3816         -  void*,
         3840  +  void *pArg,
  3817   3841     int(*xCompare)(void*,int,const void*,int,const void*),
  3818   3842     void(*xDestroy)(void*)
  3819   3843   );
  3820   3844   int sqlite3_create_collation16(
  3821   3845     sqlite3*, 
  3822   3846     const void *zName,
  3823   3847     int eTextRep, 
  3824         -  void*,
         3848  +  void *pArg,
  3825   3849     int(*xCompare)(void*,int,const void*,int,const void*)
  3826   3850   );
  3827   3851   
  3828   3852   /*
  3829   3853   ** CAPI3REF: Collation Needed Callbacks
  3830   3854   **
  3831   3855   ** ^To avoid having to register all collation sequences before a database