diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/sqlite.h.in | 104 |
1 files changed, 56 insertions, 48 deletions
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); |