/*

** 2009 November 10

**

** The author disclaims copyright to this source code. In place of

** a legal notice, here is a blessing:

**

** May you do good and not evil.

** May you find forgiveness for yourself and forgive others.

** May you share freely, never taking more than you give.

**

*************************************************************************

**

** This is the C-language interface definition for the "intarray" or

** integer array virtual table for SQLite.

**

** The intarray virtual table is designed to facilitate using an

** array of integers as the right-hand side of an IN operator. So

** instead of doing a prepared statement like this:

**

** SELECT * FROM table WHERE x IN (?,?,?,...,?);

**

** And then binding indivdual integers to each of ? slots, a C-language

** application can create an intarray object (named "ex1" in the following

** example), prepare a statement like this:

**

** SELECT * FROM table WHERE x IN ex1;

**

** Then bind an ordinary C/C++ array of integer values to the ex1 object

** to run the statement.

**

** USAGE:

**

** One or more intarray objects can be created as follows:

**

** sqlite3_intarray *p1, *p2, *p3;

** sqlite3_intarray_create(db, "ex1", &p1);

** sqlite3_intarray_create(db, "ex2", &p2);

** sqlite3_intarray_create(db, "ex3", &p3);

**

** Each call to sqlite3_intarray_create() generates a new virtual table

** module and a singleton of that virtual table module in the TEMP

** database. Both the module and the virtual table instance use the

** name given by the second parameter. The virtual tables can then be

** used in prepared statements:

**

** SELECT * FROM t1, t2, t3

** WHERE t1.x IN ex1

** AND t2.y IN ex2

** AND t3.z IN ex3;

**

** Each integer array is initially empty. New arrays can be bound to

** an integer array as follows:

**

** sqlite3_int64 a1[] = { 1, 2, 3, 4 };

** sqlite3_int64 a2[] = { 5, 6, 7, 8, 9, 10, 11 };

** sqlite3_int64 *a3 = sqlite3_malloc( 100*sizeof(sqlite3_int64) );

** // Fill in content of a3[]

** sqlite3_intarray_bind(p1, 4, a1, 0);

** sqlite3_intarray_bind(p2, 7, a2, 0);

** sqlite3_intarray_bind(p3, 100, a3, sqlite3_free);

**

** A single intarray object can be rebound multiple times. But do not

** attempt to change the bindings of an intarray while it is in the middle

** of a query.

**

** The array that holds the integers is automatically freed by the function

** in the fourth parameter to sqlite3_intarray_bind() when the array is no

** longer needed. The application must not change the intarray values

** while an intarray is in the middle of a query.

**

** The intarray object is automatically destroyed when its corresponding

** virtual table is dropped. Since the virtual tables are created in the

** TEMP database, they are automatically dropped when the database connection

** closes so the application does not normally need to take any special

** action to free the intarray objects.

*/

#include "sqlite3.h"

/*

** An sqlite3_intarray is an abstract type to stores an instance of

** an integer array.

*/

typedef struct sqlite3_intarray sqlite3_intarray;

/*

** Invoke this routine to create a specific instance of an intarray object.

** The new intarray object is returned by the 3rd parameter.

**

** Each intarray object corresponds to a virtual table in the TEMP table

** with a name of zName.

**

** Destroy the intarray object by dropping the virtual table. If not done

** explicitly by the application, the virtual table will be dropped implicitly

** by the system when the database connection is closed.

*/

int sqlite3_intarray_create(

sqlite3 *db,

const char *zName,

sqlite3_intarray **ppReturn

);

/*

** Bind a new array array of integers to a specific intarray object.

**

** The array of integers bound must be unchanged for the duration of

** any query against the corresponding virtual table. If the integer

** array does change or is deallocated undefined behavior will result.

*/

int sqlite3_intarray_bind(

sqlite3_intarray *pIntArray, /* The intarray object to bind to */

int nElements, /* Number of elements in the intarray */

sqlite3_int64 *aElements, /* Content of the intarray */

void (*xFree)(void*) /* How to dispose of the intarray when done */

);