modernc.org/cc@v1.0.1/v2/testdata/_sqlite/src/test_intarray.h (about)

     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  #ifndef SQLITE_INTARRAY_H
    79  #define SQLITE_INTARRAY_H
    80  
    81  /*
    82  ** Make sure we can call this stuff from C++.
    83  */
    84  #ifdef __cplusplus
    85  extern "C" {
    86  #endif
    87  
    88  /*
    89  ** An sqlite3_intarray is an abstract type to stores an instance of
    90  ** an integer array.
    91  */
    92  typedef struct sqlite3_intarray sqlite3_intarray;
    93  
    94  /*
    95  ** Invoke this routine to create a specific instance of an intarray object.
    96  ** The new intarray object is returned by the 3rd parameter.
    97  **
    98  ** Each intarray object corresponds to a virtual table in the TEMP table
    99  ** with a name of zName.
   100  **
   101  ** Destroy the intarray object by dropping the virtual table.  If not done
   102  ** explicitly by the application, the virtual table will be dropped implicitly
   103  ** by the system when the database connection is closed.
   104  */
   105  SQLITE_API int sqlite3_intarray_create(
   106    sqlite3 *db,
   107    const char *zName,
   108    sqlite3_intarray **ppReturn
   109  );
   110  
   111  /*
   112  ** Bind a new array array of integers to a specific intarray object.
   113  **
   114  ** The array of integers bound must be unchanged for the duration of
   115  ** any query against the corresponding virtual table.  If the integer
   116  ** array does change or is deallocated undefined behavior will result.
   117  */
   118  SQLITE_API int sqlite3_intarray_bind(
   119    sqlite3_intarray *pIntArray,   /* The intarray object to bind to */
   120    int nElements,                 /* Number of elements in the intarray */
   121    sqlite3_int64 *aElements,      /* Content of the intarray */
   122    void (*xFree)(void*)           /* How to dispose of the intarray when done */
   123  );
   124  
   125  #ifdef __cplusplus
   126  }  /* End of the 'extern "C"' block */
   127  #endif
   128  #endif /* SQLITE_INTARRAY_H */