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.
**
**
** <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
** 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);
projects / thirdparty / sqlite.git / commitdiff
