mirrors/sqlite
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki 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
Show Stats 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().
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.

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*);
/*
** 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>
** <blockquote><pre>
** &nbsp; for(rc=sqlite3_vtab_in_first(pList, &pVal);
** &nbsp; rc==SQLITE_OK && pVal
** &nbsp; rc=sqlite3_vtab_in_next(pList, &pVal)
** &nbsp; ){
** &nbsp; // do something with pVal
** &nbsp; }
** &nbsp; if( rc!=SQLITE_OK ){
** &nbsp; // an error has occurred
** &nbsp; }
** </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
** 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);