Annotation of embedaddon/sqlite3/src/test_intarray.h, revision 1.1
1.1 ! misho 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: ** The intarray virtual table is designed to facilitate using an
! 17: ** array of integers as the right-hand side of an IN operator. So
! 18: ** instead of doing a prepared statement like this:
! 19: **
! 20: ** SELECT * FROM table WHERE x IN (?,?,?,...,?);
! 21: **
! 22: ** And then binding indivdual integers to each of ? slots, a C-language
! 23: ** application can create an intarray object (named "ex1" in the following
! 24: ** example), prepare a statement like this:
! 25: **
! 26: ** SELECT * FROM table WHERE x IN ex1;
! 27: **
! 28: ** Then bind an ordinary C/C++ array of integer values to the ex1 object
! 29: ** to run the statement.
! 30: **
! 31: ** USAGE:
! 32: **
! 33: ** One or more intarray objects can be created as follows:
! 34: **
! 35: ** sqlite3_intarray *p1, *p2, *p3;
! 36: ** sqlite3_intarray_create(db, "ex1", &p1);
! 37: ** sqlite3_intarray_create(db, "ex2", &p2);
! 38: ** sqlite3_intarray_create(db, "ex3", &p3);
! 39: **
! 40: ** Each call to sqlite3_intarray_create() generates a new virtual table
! 41: ** module and a singleton of that virtual table module in the TEMP
! 42: ** database. Both the module and the virtual table instance use the
! 43: ** name given by the second parameter. The virtual tables can then be
! 44: ** used in prepared statements:
! 45: **
! 46: ** SELECT * FROM t1, t2, t3
! 47: ** WHERE t1.x IN ex1
! 48: ** AND t2.y IN ex2
! 49: ** AND t3.z IN ex3;
! 50: **
! 51: ** Each integer array is initially empty. New arrays can be bound to
! 52: ** an integer array as follows:
! 53: **
! 54: ** sqlite3_int64 a1[] = { 1, 2, 3, 4 };
! 55: ** sqlite3_int64 a2[] = { 5, 6, 7, 8, 9, 10, 11 };
! 56: ** sqlite3_int64 *a3 = sqlite3_malloc( 100*sizeof(sqlite3_int64) );
! 57: ** // Fill in content of a3[]
! 58: ** sqlite3_intarray_bind(p1, 4, a1, 0);
! 59: ** sqlite3_intarray_bind(p2, 7, a2, 0);
! 60: ** sqlite3_intarray_bind(p3, 100, a3, sqlite3_free);
! 61: **
! 62: ** A single intarray object can be rebound multiple times. But do not
! 63: ** attempt to change the bindings of an intarray while it is in the middle
! 64: ** of a query.
! 65: **
! 66: ** The array that holds the integers is automatically freed by the function
! 67: ** in the fourth parameter to sqlite3_intarray_bind() when the array is no
! 68: ** longer needed. The application must not change the intarray values
! 69: ** while an intarray is in the middle of a query.
! 70: **
! 71: ** The intarray object is automatically destroyed when its corresponding
! 72: ** virtual table is dropped. Since the virtual tables are created in the
! 73: ** TEMP database, they are automatically dropped when the database connection
! 74: ** closes so the application does not normally need to take any special
! 75: ** action to free the intarray objects.
! 76: */
! 77: #include "sqlite3.h"
! 78:
! 79: /*
! 80: ** An sqlite3_intarray is an abstract type to stores an instance of
! 81: ** an integer array.
! 82: */
! 83: typedef struct sqlite3_intarray sqlite3_intarray;
! 84:
! 85: /*
! 86: ** Invoke this routine to create a specific instance of an intarray object.
! 87: ** The new intarray object is returned by the 3rd parameter.
! 88: **
! 89: ** Each intarray object corresponds to a virtual table in the TEMP table
! 90: ** with a name of zName.
! 91: **
! 92: ** Destroy the intarray object by dropping the virtual table. If not done
! 93: ** explicitly by the application, the virtual table will be dropped implicitly
! 94: ** by the system when the database connection is closed.
! 95: */
! 96: int sqlite3_intarray_create(
! 97: sqlite3 *db,
! 98: const char *zName,
! 99: sqlite3_intarray **ppReturn
! 100: );
! 101:
! 102: /*
! 103: ** Bind a new array array of integers to a specific intarray object.
! 104: **
! 105: ** The array of integers bound must be unchanged for the duration of
! 106: ** any query against the corresponding virtual table. If the integer
! 107: ** array does change or is deallocated undefined behavior will result.
! 108: */
! 109: int sqlite3_intarray_bind(
! 110: sqlite3_intarray *pIntArray, /* The intarray object to bind to */
! 111: int nElements, /* Number of elements in the intarray */
! 112: sqlite3_int64 *aElements, /* Content of the intarray */
! 113: void (*xFree)(void*) /* How to dispose of the intarray when done */
! 114: );
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>