From 86c756015bc57a729ce2e3e188792d798d8747aa Mon Sep 17 00:00:00 2001 From: drh <> Date: Sat, 29 Jan 2022 21:41:15 +0000 Subject: [PATCH] Documentation enhancements. No code changes. FossilOrigin-Name: 312642d982f7861fd4db416e5eb24d863535b3ade40539a32f2dfe3f6fc45d46 --- manifest | 13 +++-- manifest.uuid | 2 +- src/sqlite.h.in | 123 +++++++++++++++++++++++++++++++++--------------- 3 files changed, 92 insertions(+), 46 deletions(-) diff --git a/manifest b/manifest index 6f2af601ef..cd6efcc842 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Add\sthe\sSQLITE_INDEX_CONSTRAINT_LIMIT\sand\sSQLITE_INDEX_CONSTRAINT_OFFSET\nconstraints\sto\sthe\ssqlite3_index_info\sfor\sthe\sxBestIndex\smethod\sof\svirtual\ntables. -D 2022-01-28T23:44:27.760 +C Documentation\senhancements.\s\sNo\scode\schanges. +D 2022-01-29T21:41:15.826 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724 @@ -554,7 +554,7 @@ F src/resolve.c 24032ae57aec10df2f3fa2e20be0aae7d256bc704124b76c52d763440c7c0fe9 F src/rowset.c ba9515a922af32abe1f7d39406b9d35730ed65efab9443dc5702693b60854c92 F src/select.c a6d2d4bed279d7fe4fcedaf297eaf6441e8e17c6e3947a32d24d23be52ac02f2 F src/shell.c.in e80a140e92e342e2f92d405a77155c8e3a67c9b1d0bdbacb92885960cd4fc8f2 -F src/sqlite.h.in da0e94f140f3f054f0eca8fc4a183167bedc7ae9c51822390c62369455eae5f8 +F src/sqlite.h.in eaade58049152dac850d57415bcced885ca27ae9582f8aea2cfb7f1db78a521b F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8 F src/sqlite3ext.h 5d54cf13d3406d8eb65d921a0d3c349de6126b732e695e79ecd4830ce86b4f8a F src/sqliteInt.h 8ef2996e02476f73e41ba977f819bda0cc68b7ce238cf404b9b8930df57bc1d0 @@ -1942,9 +1942,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0 -P ae088cbc968a565c3e0a8dd74ce150cac4a87978b593a3204f475fa196f1603c 388926254b9da6169da7267bd4d5a1a66a26576be435c88269ab8db9eaedc079 -R 9225571e858504f378a02e825bc79ee6 -T +closed 388926254b9da6169da7267bd4d5a1a66a26576be435c88269ab8db9eaedc079 +P 1e227ad9f413227f767b45b91e5439b82c98a3368fb20643414dab5c0f4818c6 +R f13cee5dfcfac643ce5de584b78c3f4d U drh -Z b46b82d7c9b67bbb72c40f2f1d6b1914 +Z 04ccdcba53141070401957d8ba0c3d32 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 37b532e462..b4ed546f5b 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -1e227ad9f413227f767b45b91e5439b82c98a3368fb20643414dab5c0f4818c6 \ No newline at end of file +312642d982f7861fd4db416e5eb24d863535b3ade40539a32f2dfe3f6fc45d46 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index d549a1ba4b..82f844d6a7 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -4352,6 +4352,8 @@ int sqlite3_stmt_busy(sqlite3_stmt*); ** ** ^The sqlite3_value objects that are passed as parameters into the ** implementation of [application-defined SQL functions] are protected. +** ^The sqlite3_value objects returned by [sqlite3_vtab_rhs_value()] +** are protected. ** ^The sqlite3_value object returned by ** [sqlite3_column_value()] is unprotected. ** Unprotected sqlite3_value objects may only be used as arguments @@ -7131,26 +7133,56 @@ struct sqlite3_index_info { ** ** These macros define the allowed values for the ** [sqlite3_index_info].aConstraint[].op field. Each value represents -** an operator that is part of a constraint term in the wHERE clause of +** an operator that is part of a constraint term in the WHERE clause of ** a query that uses a [virtual table]. +** +** ^The left-hand operand of the operator is given by the corresponding +** aConstraint[].iColumn field. ^An iColumn of -1 indicates the left-hand +** operand is the rowid. +** The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET +** operators have no left-hand operand, and so for those operators the +** corresponding aConstraint[].iColumn is meaningless and should not be +** used. +** +** All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through +** value 255 are reserved to represent functions that are overloaded +** by the [xFindFunction|xFindFunction method] of the virtual table +** implementation. +** +** The right-hand operands for each constraint might be accessible using +** the [sqlite3_vtab_rhs_value()] interface. Usually the right-hand +** operand is only available if it appears as a single constant literal +** in the input SQL. If the right-hand operand is another column or an +** expression (even a constant expression) or a parameter, then the +** sqlite3_vtab_rhs_value() probably will not be able to extract it. +** ^The SQLITE_INDEX_CONSTRAINT_ISNULL and +** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand +** and hence calls to sqlite3_vtab_rhs_value() for those operators will +** always return SQLITE_NOTFOUND. +** +** The collating sequence to be used for comparison can be found using +** the [sqlite3_vtab_collation()] interface. For most real-world virtual +** tables, the collating sequence of constraints does not matter (for example +** because the constraints are numeric) and so the sqlite3_vtab_collation() +** interface is no commonly needed. */ -#define SQLITE_INDEX_CONSTRAINT_EQ 2 -#define SQLITE_INDEX_CONSTRAINT_GT 4 -#define SQLITE_INDEX_CONSTRAINT_LE 8 -#define SQLITE_INDEX_CONSTRAINT_LT 16 -#define SQLITE_INDEX_CONSTRAINT_GE 32 -#define SQLITE_INDEX_CONSTRAINT_MATCH 64 -#define SQLITE_INDEX_CONSTRAINT_LIKE 65 -#define SQLITE_INDEX_CONSTRAINT_GLOB 66 -#define SQLITE_INDEX_CONSTRAINT_REGEXP 67 -#define SQLITE_INDEX_CONSTRAINT_NE 68 -#define SQLITE_INDEX_CONSTRAINT_ISNOT 69 -#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 -#define SQLITE_INDEX_CONSTRAINT_ISNULL 71 -#define SQLITE_INDEX_CONSTRAINT_IS 72 -#define SQLITE_INDEX_CONSTRAINT_LIMIT 73 -#define SQLITE_INDEX_CONSTRAINT_OFFSET 74 -#define SQLITE_INDEX_CONSTRAINT_FUNCTION 150 +#define SQLITE_INDEX_CONSTRAINT_EQ 2 +#define SQLITE_INDEX_CONSTRAINT_GT 4 +#define SQLITE_INDEX_CONSTRAINT_LE 8 +#define SQLITE_INDEX_CONSTRAINT_LT 16 +#define SQLITE_INDEX_CONSTRAINT_GE 32 +#define SQLITE_INDEX_CONSTRAINT_MATCH 64 +#define SQLITE_INDEX_CONSTRAINT_LIKE 65 +#define SQLITE_INDEX_CONSTRAINT_GLOB 66 +#define SQLITE_INDEX_CONSTRAINT_REGEXP 67 +#define SQLITE_INDEX_CONSTRAINT_NE 68 +#define SQLITE_INDEX_CONSTRAINT_ISNOT 69 +#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 +#define SQLITE_INDEX_CONSTRAINT_ISNULL 71 +#define SQLITE_INDEX_CONSTRAINT_IS 72 +#define SQLITE_INDEX_CONSTRAINT_LIMIT 73 +#define SQLITE_INDEX_CONSTRAINT_OFFSET 74 +#define SQLITE_INDEX_CONSTRAINT_FUNCTION 150 /* ** CAPI3REF: Register A Virtual Table Implementation @@ -9510,15 +9542,16 @@ SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int); ** CAPI3REF: Determine if a virtual table query is DISTINCT ** METHOD: sqlite3_index_info ** -** This API may only be used from within an xBestIndex() callback. The -** results of calling it from outside of an xBestIndex() callback are -** undefined and probably harmful. +** This API may only be used from within an [xBestIndex|xBestIndex method] +** of a [virtual table] implementation. The result of calling this +** interface from outside of xBestIndex() is undefined and probably harmful. ** -** ^The sqlite3_vtab_distinct() returns an integer that is either 0, 1, or -** 2. The integer returned by sqlite3_vtab_distinct() gives the virtual table -** additional information about how the query planner wants the output to be -** ordered. As long as the virtual table can meet the ordering requirements -** of the query planner, it may set the "orderByConsumed" flag. +** ^The sqlite3_vtab_distinct() interface returns an integer that is +** either 0, 1, or 2. The integer returned by sqlite3_vtab_distinct() +** gives the virtual table additional information about how the query +** planner wants the output to be ordered. As long as the virtual table +** can meet the ordering requirements of the query planner, it may set +** the "orderByConsumed" flag. ** **

  1. ** ^If the sqlite3_vtab_distinct() interface returns 0, that means @@ -9527,7 +9560,7 @@ SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int); ** [sqlite3_index_info] object. This is the default expectation. If the ** virtual table outputs all rows in sorted order, then it is always safe for ** the xBestIndex method to set the "orderByConsumed" flag, regardless of -** what the return value from sqlite3_vtab_distinct(). +** the return value from sqlite3_vtab_distinct(). **

  2. ** ^(If the sqlite3_vtab_distinct() interface returns 1, that means ** that the query planner does not need the rows to be returned in sorted order @@ -9540,7 +9573,7 @@ SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int); ** order, as long as rows with the same values in all "aOrderBy" columns ** are adjacent.)^ ^(Furthermore, only a single row for each particular ** combination of values in the columns identified by the "aOrderBy" field -** needs to be returned.)^ ^It is ok always for two or more rows with the same +** needs to be returned.)^ ^It is always ok for two or more rows with the same ** values in all "aOrderBy" columns to be returned, as long as all such rows ** are adjacent. ^The virtual table may, if it chooses, omit extra rows ** that have the same value for all columns identified by "aOrderBy". @@ -9575,27 +9608,41 @@ int sqlite3_vtab_distinct(sqlite3_index_info*); ** CAPI3REF: Constraint values in xBestIndex() ** METHOD: sqlite3_index_info ** -** This API may only be used from within an xBestIndex() callback. The -** results of calling it from outside of an xBestIndex() callback are -** undefined and probably harmful. +** This API may only be used from within the [xBestIndex|xBestIndex method] +** of a [virtual table] implementation. The result of calling this interface +** from outside of an xBestIndex method are undefined and probably harmful. ** ** ^When the sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within ** the [xBestIndex] method of a [virtual table] implementation, with P being ** a copy of the [sqlite3_index_info] object pointer passed into xBestIndex and ** J being a 0-based index into P->aConstraint[], then this routine -** attempts to set *V to be the value on the right-hand side of -** that constraint if the right-hand side is a known constant. ^If the -** right-hand side of the constraint is not known, then *V is set to a NULL -** pointer. ^The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if +** attempts to set *V to the value of the right-hand operand of +** that constraint if the right-hand operand is known. ^If the +** right-hand operand is not known, then *V is set to a NULL pointer. +** ^The sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if ** and only if *V is set to a value. ^The sqlite3_vtab_rhs_value(P,J,V) ** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th ** constraint is not available. ^The sqlite3_vtab_rhs_value() interface ** can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if ** something goes wrong. ** -** ^The sqlite3_value object returned in *V remains valid for the duration of -** the xBestIndex method code. ^When xBestIndex returns, the sqlite3_value -** object returned by sqlite3_vtab_rhs_value() is automatically deallocated. +** The sqlite3_vtab_rhs_value() interface is usually only successful if +** the right-hand operand of a constraint is a literal value in the original +** SQL statement. If the right-hand operand is an expression or a reference +** to some other column or a [host parameter], then sqlite3_vtab_rhs_value() +** will probably return [SQLITE_NOTFOUND]. +** +** ^(Some constraints, such as [SQLITE_INDEX_CONSTRAINT_ISNULL] and +** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand. For such +** constraints, sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.)^ +** +** ^The [sqlite3_value] object returned in *V is a protected sqlite3_value +** and remains valid for the duration of the xBestIndex method call. +** ^When xBestIndex returns, the sqlite3_value object returned by +** sqlite3_vtab_rhs_value() is automatically deallocated. +** +** The "_rhs_" in the name of this routine is an appreviation for +** "Right-Hand Side". */ int sqlite3_vtab_rhs_value(sqlite3_index_info*, int, sqlite3_value **ppVal);