Return to test_intarray.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / src

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: );