src/test_intarray.h

   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 individual 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 */