AryaWu/sqlite

1/*2** 2009 November 103**4** The author disclaims copyright to this source code.  In place of5** 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" or14** integer array virtual table for SQLite.15**16** This virtual table is used for internal testing of SQLite only.  It is17** not recommended for use in production.  For a similar virtual table that18** is production-ready, see the "carray" virtual table over in ext/misc.19**20** The intarray virtual table is designed to facilitate using an21** array of integers as the right-hand side of an IN operator.  So22** 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-language27** application can create an intarray object (named "ex1" in the following28** 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 object33** 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 table45** module and a singleton of that virtual table module in the TEMP46** database.  Both the module and the virtual table instance use the47** name given by the second parameter.  The virtual tables can then be48** used in prepared statements:49**50**      SELECT * FROM t1, t2, t351**       WHERE t1.x IN ex152**         AND t2.y IN ex253**         AND t3.z IN ex3;54**55** Each integer array is initially empty.  New arrays can be bound to56** 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 not67** attempt to change the bindings of an intarray while it is in the middle68** of a query.69**70** The array that holds the integers is automatically freed by the function71** in the fourth parameter to sqlite3_intarray_bind() when the array is no72** longer needed.  The application must not change the intarray values73** while an intarray is in the middle of a query.74**75** The intarray object is automatically destroyed when its corresponding76** virtual table is dropped.  Since the virtual tables are created in the77** TEMP database, they are automatically dropped when the database connection78** closes so the application does not normally need to take any special79** action to free the intarray objects.  Because of the way virtual tables80** work and the (somewhat goofy) way that the intarray virtual table is81** 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_H86#define SQLITE_INTARRAY_H87 88/*89** Make sure we can call this stuff from C++.90*/91#ifdef __cplusplus92extern "C" {93#endif94 95/*96** An sqlite3_intarray is an abstract type to stores an instance of97** an integer array.98*/99typedef 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 table106** with a name of zName.107**108** Destroy the intarray object by dropping the virtual table.  If not done109** explicitly by the application, the virtual table will be dropped implicitly110** by the system when the database connection is closed.111*/112SQLITE_API int sqlite3_intarray_create(113  sqlite3 *db,114  const char *zName,115  sqlite3_intarray **ppReturn116);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 of122** any query against the corresponding virtual table.  If the integer123** array does change or is deallocated undefined behavior will result.124*/125SQLITE_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 __cplusplus133}  /* End of the 'extern "C"' block */134#endif135#endif /* SQLITE_INTARRAY_H */136