1 /* 2 ** 2009 November 10 3 ** 4 ** The author disclaims copyright to this source code. In place of 5 ** a legal notice, here is a blessing: 6 ** 7 ** May you do good and not evil. 8 ** May you find forgiveness for yourself and forgive others. 9 ** May you share freely, never taking more than you give. 10 ** 11 ************************************************************************* 12 ** 13 ** This is the C-language interface definition for the "intarray" or 14 ** integer array virtual table for SQLite. 15 ** 16 ** This virtual table is used for internal testing of SQLite only. It is 17 ** not recommended for use in production. For a similar virtual table that 18 ** is production-ready, see the "carray" virtual table over in ext/misc. 19 ** 20 ** The intarray virtual table is designed to facilitate using an 21 ** array of integers as the right-hand side of an IN operator. So 22 ** instead of doing a prepared statement like this: 23 ** 24 ** SELECT * FROM table WHERE x IN (?,?,?,...,?); 25 ** 26 ** And then binding indivdual integers to each of ? slots, a C-language 27 ** application can create an intarray object (named "ex1" in the following 28 ** example), prepare a statement like this: 29 ** 30 ** SELECT * FROM table WHERE x IN ex1; 31 ** 32 ** Then bind an ordinary C/C++ array of integer values to the ex1 object 33 ** to run the statement. 34 ** 35 ** USAGE: 36 ** 37 ** One or more intarray objects can be created as follows: 38 ** 39 ** sqlite3_intarray *p1, *p2, *p3; 40 ** sqlite3_intarray_create(db, "ex1", &p1); 41 ** sqlite3_intarray_create(db, "ex2", &p2); 42 ** sqlite3_intarray_create(db, "ex3", &p3); 43 ** 44 ** Each call to sqlite3_intarray_create() generates a new virtual table 45 ** module and a singleton of that virtual table module in the TEMP 46 ** database. Both the module and the virtual table instance use the 47 ** name given by the second parameter. The virtual tables can then be 48 ** used in prepared statements: 49 ** 50 ** SELECT * FROM t1, t2, t3 51 ** WHERE t1.x IN ex1 52 ** AND t2.y IN ex2 53 ** AND t3.z IN ex3; 54 ** 55 ** Each integer array is initially empty. New arrays can be bound to 56 ** an integer array as follows: 57 ** 58 ** sqlite3_int64 a1[] = { 1, 2, 3, 4 }; 59 ** sqlite3_int64 a2[] = { 5, 6, 7, 8, 9, 10, 11 }; 60 ** sqlite3_int64 *a3 = sqlite3_malloc( 100*sizeof(sqlite3_int64) ); 61 ** // Fill in content of a3[] 62 ** sqlite3_intarray_bind(p1, 4, a1, 0); 63 ** sqlite3_intarray_bind(p2, 7, a2, 0); 64 ** sqlite3_intarray_bind(p3, 100, a3, sqlite3_free); 65 ** 66 ** A single intarray object can be rebound multiple times. But do not 67 ** attempt to change the bindings of an intarray while it is in the middle 68 ** of a query. 69 ** 70 ** The array that holds the integers is automatically freed by the function 71 ** in the fourth parameter to sqlite3_intarray_bind() when the array is no 72 ** longer needed. The application must not change the intarray values 73 ** while an intarray is in the middle of a query. 74 ** 75 ** The intarray object is automatically destroyed when its corresponding 76 ** virtual table is dropped. Since the virtual tables are created in the 77 ** TEMP database, they are automatically dropped when the database connection 78 ** closes so the application does not normally need to take any special 79 ** action to free the intarray objects. Because of the way virtual tables 80 ** work and the (somewhat goofy) way that the intarray virtual table is 81 ** implemented, it is not allowed to invoke sqlite3_intarray_create(D,N,P) 82 ** more than once with the same D and N values. 83 */ 84 #include "sqlite3.h" 85 #ifndef SQLITE_INTARRAY_H 86 #define SQLITE_INTARRAY_H 87 88 /* 89 ** Make sure we can call this stuff from C++. 90 */ 91 #ifdef __cplusplus 92 extern "C" { 93 #endif 94 95 /* 96 ** An sqlite3_intarray is an abstract type to stores an instance of 97 ** an integer array. 98 */ 99 typedef struct sqlite3_intarray sqlite3_intarray; 100 101 /* 102 ** Invoke this routine to create a specific instance of an intarray object. 103 ** The new intarray object is returned by the 3rd parameter. 104 ** 105 ** Each intarray object corresponds to a virtual table in the TEMP table 106 ** with a name of zName. 107 ** 108 ** Destroy the intarray object by dropping the virtual table. If not done 109 ** explicitly by the application, the virtual table will be dropped implicitly 110 ** by the system when the database connection is closed. 111 */ 112 SQLITE_API int sqlite3_intarray_create( 113 sqlite3 *db, 114 const char *zName, 115 sqlite3_intarray **ppReturn 116 ); 117 118 /* 119 ** Bind a new array array of integers to a specific intarray object. 120 ** 121 ** The array of integers bound must be unchanged for the duration of 122 ** any query against the corresponding virtual table. If the integer 123 ** array does change or is deallocated undefined behavior will result. 124 */ 125 SQLITE_API int sqlite3_intarray_bind( 126 sqlite3_intarray *pIntArray, /* The intarray object to bind to */ 127 int nElements, /* Number of elements in the intarray */ 128 sqlite3_int64 *aElements, /* Content of the intarray */ 129 void (*xFree)(void*) /* How to dispose of the intarray when done */ 130 ); 131 132 #ifdef __cplusplus 133 } /* End of the 'extern "C"' block */ 134 #endif 135 #endif /* SQLITE_INTARRAY_H */ 136