database/sqlite
1
0
Fork 0
mirror of https://github.com/sqlite/sqlite.git synced 2025-11-16 23:02:26 +03:00
Code Activity

Improved documentation for sqlite3_vtab_in(). No code changes.

Browse Source 
FossilOrigin-Name: c99df4ab5db2c32b044366c5b0ac70fd8887d1456d53323e75fede23cc61c236
This commit is contained in:
drh
2022-02-02 18:47:56 +00:00
parent 3d7a69e5ef
commit 2725db836b
3 changed files with 62 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
manifest
View File

@@ -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(). C Improved\sdocumentation\sfor\ssqlite3_vtab_in().\s\sNo\scode\schanges.
D 2022-02-02T16:24:01.752 D 2022-02-02T18:47:56.749
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -554,7 +554,7 @@ F src/resolve.c 24032ae57aec10df2f3fa2e20be0aae7d256bc704124b76c52d763440c7c0fe9
F src/rowset.c ba9515a922af32abe1f7d39406b9d35730ed65efab9443dc5702693b60854c92 F src/rowset.c ba9515a922af32abe1f7d39406b9d35730ed65efab9443dc5702693b60854c92
F src/select.c a6d2d4bed279d7fe4fcedaf297eaf6441e8e17c6e3947a32d24d23be52ac02f2 F src/select.c a6d2d4bed279d7fe4fcedaf297eaf6441e8e17c6e3947a32d24d23be52ac02f2
F src/shell.c.in 2f58e6aa6b3d2012db32f1c5fa4591e9d12fd582904632b4fc8f57a382b98fd3 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/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
F src/sqlite3ext.h a95cb9ed106e3d39e2118e4dcc15a14faec3fa50d0093425083d340d9dfd96e6 F src/sqlite3ext.h a95cb9ed106e3d39e2118e4dcc15a14faec3fa50d0093425083d340d9dfd96e6
F src/sqliteInt.h 838df3e9ba9390058076d2f50c7efde9e0e8747303e788cf5bbe05402ab10924 F src/sqliteInt.h 838df3e9ba9390058076d2f50c7efde9e0e8747303e788cf5bbe05402ab10924
@@ -1942,8 +1942,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
P 04edf36ee8e043c83235a5169a7ced23f211edd2f7ef3290d96413d5fd229ad7 P 3bf2153440dce0e8c0572c4fd39e6b9f34ead75ccab2cea80a646d4ff9d19146
R 2c3c1902f73f372b9534bd85d910dc24 R f229e1cc04b78384226f7f6c44d75044
U drh U drh
Z bd0932878b05cf48df93c8b67c69411f Z 5557e45c47098a153d05816f88cff23e
# Remove this line to create a well-formed Fossil manifest. # Remove this line to create a well-formed Fossil manifest.

2
manifest.uuid
View File

@@ -1 +1 @@
3bf2153440dce0e8c0572c4fd39e6b9f34ead75ccab2cea80a646d4ff9d19146 c99df4ab5db2c32b044366c5b0ac70fd8887d1456d53323e75fede23cc61c236

102
src/sqlite.h.in
View File

@@ -9605,21 +9605,22 @@ SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
int sqlite3_vtab_distinct(sqlite3_index_info*); 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 ** 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 ** The result of invoking this interface from any other context is
** undefined and probably harmful. ** 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 ** 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 ** this constraint, it must set the corresponding
** aConstraintUsage[].argvIndex to a postive integer. Then, under ** aConstraintUsage[].argvIndex to a postive integer. ^(Then, under
** the usual mode of handling IN operators, SQLite generate bytecode ** the usual mode of handling IN operators, SQLite generates [bytecode]
** that invokes the [xFilter|xFilter() method] once for each value ** 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 ** only sees a single value from the right-hand side of the IN operator
** at a time. ** at a time.
** **
@@ -9629,45 +9630,46 @@ int sqlite3_vtab_distinct(sqlite3_index_info*);
** **
** <ol> ** <ol>
** <li><p> ** <li><p>
** A call to sqlite3_vtab_in(P,I,-1) will return true (non-zero) ** ^A call to sqlite3_vtab_in(P,N,-1) will return true (non-zero)
** if and only if the I-th constraint in P->aConstraint[] is ** if and only if the [sqlite3_index_info|P->aConstraint][N] constraint
** an IN operator that can be processed all at once. In other words, ** 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 ** 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 ** by which the virtual table can ask SQLite if all-at-once processing
** of the IN operator is even possible. ** of the IN operator is even possible.
** **
** <li><p> ** <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 ** 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 ** the IN operator all-at-once, respectively. ^Thus when the third
** non-negative, this interface is the mechanism by which the virtual ** parameter (F) is non-negative, this interface is the mechanism by
** table tells SQLite how it wants to process in IN operator. ** which the virtual table tells SQLite how it wants to process in
** IN operator.
** </ol> ** </ol>
** **
** The sqlite3_vtab_in(P,I,F) interface can be invoked multiple times ** ^The sqlite3_vtab_in(P,N,F) interface can be invoked multiple times
** within the same xBestIndex method call. For any given P and I parameters, ** within the same xBestIndex method call. ^For any given P,N pair,
** the return value from sqlite3_vtab_in(P,I,F) will always be the same ** the return value from sqlite3_vtab_in(P,N,F) will always be the same
** for every invocation within the same xBestIndex call. If the interface ** within the same xBestIndex call. ^If the interface returns true
** returns true (non-zero), that means that the constraint is an IN operator ** (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 ** 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 ** operator or cannot be processed all-at-once, then the interface returns
** false. ** 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: ** following conditions are met:
** **
** <ol> ** <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 ** 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. ** non-negative had F>=1.
** </ol> ** </ol>)^
** **
** If either or both of the conditions above are false, then uses the ** ^If either or both of the conditions above are false, then SQLite uses
** traditional one-at-a-time processing strategy for IN constraint. ** the traditional one-at-a-time processing strategy for IN constraint.
** If both conditions are true, then the argvIndex-th parameter to the ** ^If both conditions are true, then the argvIndex-th parameter to the
** xFilter method will be an [sqlite3_value] that appears to be NULL, ** xFilter method will be an [sqlite3_value] that appears to be NULL,
** but which can be passed to [sqlite3_vtab_in_first()] and ** but which can be passed to [sqlite3_vtab_in_first()] and
** [sqlite3_vtab_in_next()] to find all values on the right-hand side ** [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. ** CAPI3REF: Find all elements on the right-hand side of an IN constraint.
** **
** These interfaces are only useful from within the ** 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 ** The result of invoking these interfaces from any other context
** is undefined and probably harmful. ** is undefined and probably harmful.
** **
** The X parameter in a call to sqlite3_vtab_in_first(X,P) or ** 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 ** 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 ** a parameter that was previously selected for all-at-once IN constraint
** processing use the [sqlite3_vtab_in()] interface in the ** 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 ** 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. ** 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: ** of the IN constraint using code like the following:
** **
** <pre> ** <blockquote><pre>
** for(rc=sqlite3_vtab_in_first(pList, &pVal); ** &nbsp; for(rc=sqlite3_vtab_in_first(pList, &pVal);
** rc==SQLITE_OK && pVal ** &nbsp; rc==SQLITE_OK && pVal
** rc=sqlite3_vtab_in_next(pList, &pVal) ** &nbsp; rc=sqlite3_vtab_in_next(pList, &pVal)
** ){ ** &nbsp; ){
** // do something with pVal ** &nbsp; // do something with pVal
** } ** &nbsp; }
** if( rc!=SQLITE_OK ){ ** &nbsp; if( rc!=SQLITE_OK ){
** // an error has occurred ** &nbsp; // an error has occurred
** } ** &nbsp; }
** </pre> ** </pre></blockquote>)^
** **
** On success, the sqlite3_vtab_in_first(X,P) and sqlite3_vtab_in_next(X,P) ** ^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 ** 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 ** 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. ** 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_first(sqlite3_value *pVal, sqlite3_value **ppOut);
int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut); int sqlite3_vtab_in_next(sqlite3_value *pVal, sqlite3_value **ppOut);