Clarify the documentation of the sqlite3_create_function API.

Ticket #1004. (CVS 2108)

FossilOrigin-Name: ae45ad863b0854b96da31321c500e3168ef103ad

diff --git a/manifest b/manifest
index 5003cf12d1f0ca6cc2ad38981a41c2aec0ae1490..f3458dbc2e17406e47c5781090d858e14db0a401 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Add\sthe\sESCAPE\sclause\sto\sthe\sLIKE\soperator.\sNot\sfully\stested\syet.\s(CVS\s2107)
-D 2004-11-17T16:41:29
+C Clarify\sthe\sdocumentation\sof\sthe\ssqlite3_create_function\sAPI.\nTicket\s#1004.\s(CVS\s2108)
+D 2004-11-18T02:04:10
 F Makefile.in e747bb5ba34ccbdd81f79dcf1b2b33c02817c21d
 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
 F README a01693e454a00cc117967e3f9fdab2d4d52e9bc1
@@ -227,7 +227,7 @@ F www/arch2b.fig d22a2c9642d584b89d4088b1e51e2bb0f7c04bed
 F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
 F www/c_interface.tcl ea5a73b330a7006df87d0a4029569301bbd72029
 F www/capi3.tcl 5c1cb163f4d2a54e2d0e22dcc399dd71245c8b89
-F www/capi3ref.tcl aa8b12a1c633c5aaca03657e8ed04c963cb698c6
+F www/capi3ref.tcl 28e70284fb1a833dbc513b9972cb0a245d4a7d60
 F www/changes.tcl f2b34859843d9f06a0611eb6d44af767891b09ef
 F www/common.tcl 690d0f159cc5b83590707797acbcd031af8079a6
 F www/conflict.tcl cdd0f4b59b0ba6d61f67e6a38f3ae45853bacb30
@@ -259,7 +259,7 @@ F www/tclsqlite.tcl 560ecd6a916b320e59f2917317398f3d59b7cc25
 F www/vdbe.tcl 095f106d93875c94b47367384ebc870517431618
 F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0
 F www/whentouse.tcl fdacb0ba2d39831e8a6240d05a490026ad4c4e4c
-P e1530854c9004c25f5ffa21f9cfb9c44c83cc7f0
-R fc41b89835631b13a4149106e5db9d17
-U danielk1977
-Z a4a4e7382bd227dede1f241a7eed092d
+P 49268c2b7a84c4c618214dac8bef0f541440fe6b
+R c7e2f2bcd67bb83b19d12dfad1291e08
+U drh
+Z e7702686ea3300d9e8466a18af72cd51

diff --git a/manifest.uuid b/manifest.uuid
index 22885cbb5837b6a420a64e0b319e8d13b22846e0..6e3efc523a5b07cd5e3a125fc641e63e49a93e1f 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-49268c2b7a84c4c618214dac8bef0f541440fe6b
\ No newline at end of file
+ae45ad863b0854b96da31321c500e3168ef103ad
\ No newline at end of file

diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl
index 92e084d03a1ca8d3ec39700e13ebd6655ebf44ef..8b8696c6afe836f490c2cb237ec35dafb9f6b15e 100644 (file)
--- a/www/capi3ref.tcl
+++ b/www/capi3ref.tcl
@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.14 2004/10/10 17:24:54 drh Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.15 2004/11/18 02:04:10 drh Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -476,7 +476,7 @@ int sqlite3_create_function(
   const char *zFunctionName,
   int nArg,
   int eTextRep,
-  void*,
+  void *pUserData,
   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
   void (*xFinal)(sqlite3_context*)
@@ -486,7 +486,7 @@ int sqlite3_create_function16(
   const void *zFunctionName,
   int nArg,
   int eTextRep,
-  void*,
+  void *pUserData,
   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
   void (*xFinal)(sqlite3_context*)
@@ -513,6 +513,19 @@ int sqlite3_create_function16(
  aggregate takes. If this parameter is negative, then the function or
  aggregate may take any number of arguments.
 
+ The fourth parameter, eTextRep, specifies what type of text arguments
+ this function prefers to receive.  Any function should be able to work
+ work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
+ more efficient with one representation than another.  Users are allowed
+ to specify separate implementations for the same function which are called
+ depending on the text representation of the arguments.  The the implementation
+ which provides the best match is used.  If there is only a single
+ implementation which does not care what text representation is used,
+ then the fourth parameter should be SQLITE_ANY.
+
+ The fifth parameter is an arbitrary pointer.  The function implementations
+ can gain access to this pointer using the sqlite_user_data() API.
+
  The sixth, seventh and  eighth, xFunc, xStep and xFinal, are
  pointers to user implemented C functions that implement the user
  function or aggregate. A scalar function requires an implementation of