diff options
| -rw-r--r-- | manifest | 12 | ||||
| -rw-r--r-- | manifest.uuid | 2 | ||||
| -rw-r--r-- | src/sqlite.h.in | 104 |
3 files changed, 63 insertions, 55 deletions
@@ -1,5 +1,5 @@ -C Relax\sthe\srestriction\sthat\sthe\sRHS\sof\sthe\sIN\soperator\smust\sbe\sa\slist\sin\sorder\nfor\ssqlite3_vtab_in()\sto\swork.\s\sChange\san\sunreachable\sbranch\sinto\san\sassert(). -D 2022-02-02T16:24:01.752 +C Improved\sdocumentation\sfor\ssqlite3_vtab_in().\s\sNo\scode\schanges. +D 2022-02-02T18:47:56.749 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 2f58e6aa6b3d2012db32f1c5fa4591e9d12fd582904632b4fc8f57a382b98fd3 -F src/sqlite.h.in 72f3e57c4c0b4284ab9238312f7fd797967cc43f44558a80469a3d9b86a7be2b +F src/sqlite.h.in a6e6fd9defb576af6444a85f446aaa738dea3384c48db4fe9007fb8ff954b7c5 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8 F src/sqlite3ext.h a95cb9ed106e3d39e2118e4dcc15a14faec3fa50d0093425083d340d9dfd96e6 F src/sqliteInt.h 838df3e9ba9390058076d2f50c7efde9e0e8747303e788cf5bbe05402ab10924 @@ -1942,8 +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 04edf36ee8e043c83235a5169a7ced23f211edd2f7ef3290d96413d5fd229ad7 -R 2c3c1902f73f372b9534bd85d910dc24 +P 3bf2153440dce0e8c0572c4fd39e6b9f34ead75ccab2cea80a646d4ff9d19146 +R f229e1cc04b78384226f7f6c44d75044 U drh -Z bd0932878b05cf48df93c8b67c69411f +Z 5557e45c47098a153d05816f88cff23e # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 3180a6bf7..472918b74 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -3bf2153440dce0e8c0572c4fd39e6b9f34ead75ccab2cea80a646d4ff9d19146
\ No newline at end of file +c99df4ab5db2c32b044366c5b0ac70fd8887d1456d53323e75fede23cc61c236
\ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index e8122912e..ead938a7d 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -9605,21 +9605,22 @@ SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int); int sqlite3_vtab_distinct(sqlite3_index_info*); /* -** CAPI3REF: Identify and handle IN(...) constraints in xBestIndex +** CAPI3REF: Identify and handle IN constraints in xBestIndex ** ** This interface may only be used from within an -** [xBestIndex|xBestIndex() method of a [virtual table] implementation. +** [xBestIndex|xBestIndex() method] of a [virtual table] implementation. ** The result of invoking this interface from any other context is ** undefined and probably harmful. ** -** A constraint on a virtual table of the form "column IN (...)" is +** ^(A constraint on a virtual table of the form +** "[IN operator|column IN (...)]" is ** communicated to the xBestIndex method as a -** [SQLITE_INDEX_CONSTRAINT_EQ] constraint. If xBestIndex wants to use +** [SQLITE_INDEX_CONSTRAINT_EQ] constraint.)^ If xBestIndex wants to use ** this constraint, it must set the corresponding -** aConstraintUsage[].argvIndex to a postive integer. Then, under -** the usual mode of handling IN operators, SQLite generate bytecode +** aConstraintUsage[].argvIndex to a postive integer. ^(Then, under +** the usual mode of handling IN operators, SQLite generates [bytecode] ** that invokes the [xFilter|xFilter() method] once for each value -** on the right-hand side of the IN operator. Thus the virtual table +** on the right-hand side of the IN operator.)^ Thus the virtual table ** only sees a single value from the right-hand side of the IN operator ** at a time. ** @@ -9629,45 +9630,46 @@ int sqlite3_vtab_distinct(sqlite3_index_info*); ** ** <ol> ** <li><p> -** A call to sqlite3_vtab_in(P,I,-1) will return true (non-zero) -** if and only if the I-th constraint in P->aConstraint[] is -** an IN operator that can be processed all at once. In other words, +** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero) +** if and only if the [sqlite3_index_info|P->aConstraint][N] constraint +** is an [IN operator] that can be processed all at once. ^In other words, ** sqlite3_vtab_in() with -1 in the third argument is a mechanism ** by which the virtual table can ask SQLite if all-at-once processing ** of the IN operator is even possible. ** ** <li><p> -** A call to sqlite3_vtab_in(P,I,F) with F set to 1 or 0 indicates +** ^A call to sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates ** to SQLite that the virtual table does or does not want to process -** the IN operator all-at-once. Thus when the third parameter (F) is -** non-negative, this interface is the mechanism by which the virtual -** table tells SQLite how it wants to process in IN operator. +** the IN operator all-at-once, respectively. ^Thus when the third +** parameter (F) is non-negative, this interface is the mechanism by +** which the virtual table tells SQLite how it wants to process in +** IN operator. ** </ol> ** -** The sqlite3_vtab_in(P,I,F) interface can be invoked multiple times -** within the same xBestIndex method call. For any given P and I parameters, -** the return value from sqlite3_vtab_in(P,I,F) will always be the same -** for every invocation within the same xBestIndex call. If the interface -** returns true (non-zero), that means that the constraint is an IN operator -** that can be processed all-at-once. If the constraint is not an IN +** ^The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times +** within the same xBestIndex method call. ^For any given P,N pair, +** the return value from sqlite3_vtab_in(P,N,F) will always be the same +** within the same xBestIndex call. ^If the interface returns true +** (non-zero), that means that the constraint is an IN operator +** that can be processed all-at-once. ^If the constraint is not an IN ** operator or cannot be processed all-at-once, then the interface returns ** false. ** -** All-at-once processing of the IN operator is selected if both of the +** ^(All-at-once processing of the IN operator is selected if both of the ** following conditions are met: ** ** <ol> -** <li><p> The P->aConstraintUsage[I].argvIndex value is set to a positive +** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive ** integer. This is how the virtual table tells SQLite that it wants to -** use the I-th constraint. +** use the N-th constraint. ** -** <li><p> The last call to sqlite3_vtab_in(P,I,F) for which F was +** <li><p> The last call to sqlite3_vtab_in(P,N,F) for which F was ** non-negative had F>=1. -** </ol> +** </ol>)^ ** -** If either or both of the conditions above are false, then uses the -** traditional one-at-a-time processing strategy for IN constraint. -** If both conditions are true, then the argvIndex-th parameter to the +** ^If either or both of the conditions above are false, then SQLite uses +** the traditional one-at-a-time processing strategy for IN constraint. +** ^If both conditions are true, then the argvIndex-th parameter to the ** xFilter method will be an [sqlite3_value] that appears to be NULL, ** but which can be passed to [sqlite3_vtab_in_first()] and ** [sqlite3_vtab_in_next()] to find all values on the right-hand side @@ -9679,41 +9681,47 @@ int sqlite3_vtab_in(sqlite3_index_info*, int iCons, int bHandle); ** CAPI3REF: Find all elements on the right-hand side of an IN constraint. ** ** These interfaces are only useful from within the -** [xFilter|xFilter() method] of a virtual table implementation. +** [xFilter|xFilter() method] of a [virtual table] implementation. ** The result of invoking these interfaces from any other context ** is undefined and probably harmful. ** ** The X parameter in a call to sqlite3_vtab_in_first(X,P) or ** sqlite3_vtab_in_next(X,P) must be one of the parameters to the -** xFilter method which invokes those routines, and specifically +** xFilter method which invokes these routines, and specifically ** a parameter that was previously selected for all-at-once IN constraint ** processing use the [sqlite3_vtab_in()] interface in the -** [xBestIndex|xBestIndex method]. If the X parameter is not +** [xBestIndex|xBestIndex method]. ^(If the X parameter is not ** an xFilter argument that was selected for all-at-once IN constraint -** processing, then these routines return SQLITE_MISUSE or perhaps +** processing, then these routines return [SQLITE_MISUSE])^ or perhaps ** exhibit some other undefined or harmful behavior. ** -** Use these routines to access all values on the right-hand side +** ^(Use these routines to access all values on the right-hand side ** of the IN constraint using code like the following: ** -** <pre> -** for(rc=sqlite3_vtab_in_first(pList, &pVal); -** rc==SQLITE_OK && pVal -** rc=sqlite3_vtab_in_next(pList, &pVal) -** ){ -** // do something with pVal -** } -** if( rc!=SQLITE_OK ){ -** // an error has occurred -** } -** </pre> -** -** On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P) +** <blockquote><pre> +** for(rc=sqlite3_vtab_in_first(pList, &pVal); +** rc==SQLITE_OK && pVal +** rc=sqlite3_vtab_in_next(pList, &pVal) +** ){ +** // do something with pVal +** } +** if( rc!=SQLITE_OK ){ +** // an error has occurred +** } +** </pre></blockquote>)^ +** +** ^On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P) ** routines return SQLITE_OK and set *P to point to the first or next value -** on the RHS of the IN constraint. If there are no more values on the +** on the RHS of the IN constraint. ^If there are no more values on the ** right hand side of the IN constraint, then *P is set to NULL and these -** routines return [SQLITE_DONE]. The return value might be +** routines return [SQLITE_DONE]. ^The return value might be ** some other value, such as SQLITE_NOMEM, in the event of a malfunction. +** +** The *ppOut values returned by these routines are only valid until the +** next call to either of these routines or until the end of the xFilter +** method from which these routines were called. If the virtual table +** implementation needs to retain the *ppOut values for longer, it must make +** copies. */ int sqlite3_vtab_in_first(sqlite3_value *pVal, sqlite3_value **ppOut); int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut); |