Thanks to visit codestin.com
Credit goes to chromium.googlesource.com

Google Git
Sign in
chromium / external / github.com / sqlite / sqlite / HEAD / . / src / test_intarray.h
blob: b68233b12af8ee7466544c9a8561c3578e9ead8f [file] [log] [blame]
drh522efc62009-11-10 17:24:37[diff] [blame]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**
drhf8181ea2018-10-31 18:24:29[diff] [blame]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**
drh522efc62009-11-10 17:24:37[diff] [blame]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**
larrybrbc917382023-06-07 08:40:31[diff] [blame]26** And then binding individual integers to each of ? slots, a C-language
drh522efc62009-11-10 17:24:37[diff] [blame]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
drhf8181ea2018-10-31 18:24:29[diff] [blame]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.
drh522efc62009-11-10 17:24:37[diff] [blame]83*/
84#include "sqlite3.h"
drh43f58d62016-07-09 16:14:45[diff] [blame]85#ifndef SQLITE_INTARRAY_H
86#define SQLITE_INTARRAY_H
drh522efc62009-11-10 17:24:37[diff] [blame]87
88/*
drh6e227bf2012-10-29 14:27:26[diff] [blame]89** Make sure we can call this stuff from C++.
90*/
91#ifdef __cplusplus
92extern "C" {
93#endif
94
95/*
drh522efc62009-11-10 17:24:37[diff] [blame]96** An sqlite3_intarray is an abstract type to stores an instance of
97** 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 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*/
drhfb908412014-08-20 13:25:06[diff] [blame]112SQLITE_API int sqlite3_intarray_create(
drh522efc62009-11-10 17:24:37[diff] [blame]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*/
drhfb908412014-08-20 13:25:06[diff] [blame]125SQLITE_API int sqlite3_intarray_bind(
drh522efc62009-11-10 17:24:37[diff] [blame]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);
drh6e227bf2012-10-29 14:27:26[diff] [blame]131
132#ifdef __cplusplus
133} /* End of the 'extern "C"' block */
134#endif
drh43f58d62016-07-09 16:14:45[diff] [blame]135#endif /* SQLITE_INTARRAY_H */