/sqlite3cc

To get this branch, use:
bzr branch http://bzr.ed.am/sqlite3cc

« back to all changes in this revision

Viewing changes to include/sqlite3cc/basic_statement.h

  • Committer: edam
  • Date: 2010-07-27 15:46:42 UTC
  • Revision ID: edam@waxworlds.org-20100727154642-1uxrjkpxhp7xl6hq
- moved null_t, exec_t and set_index_t to detail namespace so only their extern instantiations are in the main namespace
- added immediate transation

Show diffs side-by-side

added added

removed removed

include/sqlite3cc/basic_statement.h
1
1
/*
2
2
 * basic_statement.h
3
3
 *
4
 
 * Copyright (C) 2009 Tim Marston <tim@ed.am>
 
4
 * Copyright (C) 2009 Tim Marston <edam@waxworlds.org>
5
5
 *
6
6
 * This file is part of sqlite3cc (hereafter referred to as "this program").
7
 
 * See http://ed.am/dev/sqlite3cc for more information.
8
 
 *
9
 
 * This program is free software: you can redistribute it and/or modify it under
10
 
 * the terms of the GNU Lesser General Public License as published by the Free
11
 
 * Software Foundation, either version 3 of the License, or (at your option) any
12
 
 * later version.
13
 
 *
14
 
 * This program is distributed in the hope that it will be useful, but WITHOUT
15
 
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16
 
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
17
 
 * details.
 
7
 * See http://www.waxworlds.org/edam/software/sqlite3cc for more information.
 
8
 *
 
9
 * This program is free software: you can redistribute it and/or modify
 
10
 * it under the terms of the GNU Lesser General Public License as published
 
11
 * by the Free Software Foundation, either version 3 of the License, or
 
12
 * (at your option) any later version.
 
13
 *
 
14
 * This program is distributed in the hope that it will be useful,
 
15
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
16
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
17
 * GNU Lesser General Public License for more details.
18
18
 *
19
19
 * You should have received a copy of the GNU Lesser General Public License
20
20
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
34
34
{
35
35
 
36
36
 
37
 
class connection;
 
37
class database;
38
38
class row;
39
39
namespace detail {
40
40
        struct null_t;
43
43
}
44
44
 
45
45
 
46
 
namespace detail
47
 
{
48
 
 
49
 
 
50
46
/**
51
 
 * The statement class represents an SQL statement.  It is the base class for
 
47
 * The statement class represents an SQL statement. It is the base class for
52
48
 * both the command and the query classes, which should be used for those
53
 
 * purposes.  The basic_statement class its self has protected instantiation.
 
49
 * purposes. The basic_statement class its self has protected instantiation.
54
50
 */
55
51
class basic_statement
 
52
        :
 
53
        private boost::noncopyable
56
54
{
57
55
//______________________________________________________________________________
58
56
//                                                                 instantiation
59
57
protected:
60
58
 
61
59
        /**
62
 
         * Constructor that provides a connection upon which to act and the SQL
 
60
         * Constructor that provides a database upon which to act and the SQL
63
61
         * statement.
64
 
         *
65
 
         * @param connection a reference to a connection
 
62
         * @param database a reference to a database
66
63
         * @param sql an SQL statement in UTF-8
67
64
         */
68
65
        explicit basic_statement(
69
 
                connection &connection,
 
66
                database &database,
70
67
                const std::string &sql );
71
68
 
72
69
        /**
73
 
         * Constructor that provides a connection upon which to act.
74
 
         *
75
 
         * @param connection a reference to a connection
 
70
         * Constructor that provides a database upon which to act.
 
71
         * @param database a reference to a database
 
72
         * @param sql an SQL statement in UTF-8
76
73
         */
77
74
        explicit basic_statement(
78
 
                connection &connection );
 
75
                database &database );
79
76
 
80
77
        virtual ~basic_statement();
81
78
 
85
82
 
86
83
        /**
87
84
         * Prepare an SQL statement.
88
 
         *
89
85
         * @param sql an SQL statement in UTF-8
90
86
         * @returns an sqlite error code
91
87
         * @see sqlite3_prepare_v2()
94
90
                const std::string &sql );
95
91
 
96
92
        /**
97
 
         * Reset the statement, ready to re-execute it.  This does not clear any of
 
93
         * Reset the statement, ready to re-execute it. This does not clear any of
98
94
         * the values bound to the statement.
99
 
         *
100
95
         * @returns an sqlite error code
101
96
         * @see sqlite3_reset()
102
97
         */
103
 
        virtual int reset();
 
98
        int reset();
104
99
 
105
100
        /**
106
101
         * Clears the values bound to a statement to NULL.
107
 
         *
108
102
         * @returns an sqlite error code
109
103
         * @see sqlite3_clear_bindings()
110
104
         */
111
105
        int clear_bindings();
112
106
 
113
107
        /**
114
 
         * Bind a value to the SQL statement via it's index.  This template will
115
 
         * take a variety of data types and bind them as text.  This is how sqlite
 
108
         * Bind a value to the SQL statement via it's index. This template will take
 
109
         * a variety of data types and bind them as text. This is how sqlite
116
110
         * internally stores the data anyway, so always binding as text just means
117
111
         * we do the conversion instead of sqlite and is no less efficient.
118
 
         *
119
112
         * @param index the index of the parameter to bind to
120
113
         * @param value the value to bind
121
114
         * @returns an sqlite error code
133
126
 
134
127
        /**
135
128
         * Bind a string value to the SQL statement via it's index where the value
136
 
         * of that string will not change for the duration of the statement.  This
137
 
         * is more optimal because sqlite will not have to take it's own copy of the
 
129
         * of that string will not change for the duration of the statement. This is
 
130
         * more optimal because sqlite will not have to make it's own copy of the
138
131
         * data.
139
 
         *
140
132
         * @param index the index of the parameter to bind to
141
133
         * @param value the invariant string value
142
 
         * @param value_length the length of the string including zero-terminator
143
134
         * @returns an sqlite error code
144
135
         * @see sqlite3_bind_text()
145
136
         */
150
141
 
151
142
        /**
152
143
         * Bind a string value to the SQL statement via it's index where the value
153
 
         * of that string will not change for the duration of the statement.  This
154
 
         * is more optimal because sqlite will not have to take it's own copy of the
 
144
         * of that string will not change for the duration of the statement. This is
 
145
         * more optimal  because sqlite will not have to make it's own copy of the
155
146
         * data.
156
 
         *
157
147
         * @param index the index of the parameter to bind to
158
148
         * @param value the invariant string value
159
149
         * @returns an sqlite error code
165
155
 
166
156
        /**
167
157
         * Bind a string value to the SQL statement via it's index where the value
168
 
         * of that string will not change for the duration of the statement.  This
169
 
         * is more optimal because sqlite will not have to take it's own copy of the
 
158
         * of that string will not change for the duration of the statement. This is
 
159
         * more optimal because sqlite will not have to make it's own copy of the
170
160
         * data.
171
 
         *
172
161
         * @param index the index of the parameter to bind to
173
162
         * @param value the invariant string value
174
163
         * @returns an sqlite error code
180
169
 
181
170
        /**
182
171
         * Bind a NULL value to the SQL statement via it's index.
183
 
         *
184
172
         * @param index the index of the parameter to bind to
185
173
         * @returns an sqlite error code
186
174
         * @see sqlite3_bind_null()
189
177
                unsigned int index );
190
178
 
191
179
        /**
192
 
         * Bind a value to the SQL statement via a named parameter.  This template
193
 
         * will take a variety of data types and bind them as text.  This is how
 
180
         * Bind a value to the SQL statement via a named parameter. This template
 
181
         * will take a variety of data types and bind them as text. This is how
194
182
         * sqlite internally stores the data anyway, so always binding as text just
195
183
         * means we do the conversion instead of sqlite and is no less efficient.
196
 
         *
197
184
         * @param name the named parameter to bind to
198
185
         * @param value the value to bind
199
186
         * @returns an sqlite error code
209
196
 
210
197
        /**
211
198
         * Bind a string value to the SQL statement via a named parameter where the
212
 
         * string value will not change for the duration of the statement.  This
213
 
         * prevents sqlite from taking its own copy of the string.
214
 
         *
 
199
         * string value will not change for the duration of the statement. This
 
200
         * prevents a copy of the string being taken.
215
201
         * @param name the named parameter to bind to
216
202
         * @param value the invariant string value
217
 
         * @param value_length the length of the string including zero-terminator
218
203
         * @returns an sqlite error code
219
204
         * @see sqlite3_bind_text()
220
205
         */
225
210
 
226
211
        /**
227
212
         * Bind a string value to the SQL statement via a named parameter where the
228
 
         * string value will not change for the duration of the statement.  This
 
213
         * string value will not change for the duration of the statement. This
229
214
         * prevents a copy of the string being taken.
230
 
         *
231
215
         * @param name the named parameter to bind to
232
216
         * @param value the invariant string value
233
217
         * @returns an sqlite error code
239
223
 
240
224
        /**
241
225
         * Bind a string value to the SQL statement via a named parameter where the
242
 
         * string value will not change for the duration of the statement.  This
 
226
         * string value will not change for the duration of the statement. This
243
227
         * prevents a copy of the string being taken.
244
 
         *
245
228
         * @param name the named parameter to bind to
246
229
         * @param value the invariant string value
247
230
         * @returns an sqlite error code
253
236
 
254
237
        /**
255
238
         * Bind a NULL value to the SQL statement via a named parameter.
256
 
         *
257
239
         * @param name the named parameter to bind to
258
240
         * @returns an sqlite error code
259
241
         * @see sqlite3_bind_null()
263
245
 
264
246
        /**
265
247
         * Stream operator is used to bind values to parameters automatically, in
266
 
         * ascending order.  In addition, the null and set_index() auto-binding
267
 
         * manipulators can be used.
268
 
         *
 
248
         * ascending order. In addition, the null, set_index() and execute auto-
 
249
         * binding manipulators can be used.
269
250
         * @param value a value to bind
270
251
         */
271
252
        template< class T >
272
253
        basic_statement &operator <<(
273
254
                const T &value )
274
255
        {
275
 
                int code = bind( _bind_index, value );
276
 
                if( code != SQLITE_OK ) throw sqlite_error( _connection, code );
 
256
                int error_code = bind( _bind_index, value );
 
257
                if( error_code != SQLITE_OK ) throw sqlite_error( error_code );
277
258
                _bind_index++;
278
259
                return *this;
279
260
        }
286
267
 
287
268
        /**
288
269
         * Finalise an SQL statement.
289
 
         *
290
270
         * @returns an sqlite error code
291
271
         * @see sqlite3_finalize()
292
272
         */
293
273
        int finalize();
294
274
 
295
275
        /**
296
 
         * Get the index number of a named parameter.
297
 
         *
 
276
         * Step through one execution cycle of the SQL statement. If this is an SQL
 
277
         * statement that doesn't return any rows, only one cycle is required,
 
278
         * otherwise, each cycle will return another row
 
279
         * @return an sqlite error code
 
280
         * @see sqlite3_step()
 
281
         */
 
282
        int step();
 
283
 
 
284
        /**
 
285
         * Get the index number of a named parameter
298
286
         * @param parameter name
299
287
         * @return index of named parameter
300
288
         */
301
289
        int bind_parameter_index(
302
290
                const std::string &name );
303
291
 
304
 
        /**
305
 
         * Perform a step.
306
 
         *
307
 
         * @return sqlite error code
308
 
         * @see sqlite3_step()
309
 
         */
310
 
        int step();
311
 
 
312
 
        /** the connection upon which to act */
313
 
        connection &_connection;
 
292
        /** the database upon which to act */
 
293
        database &_database;
314
294
 
315
295
        /** the statement handle */
316
296
        sqlite3_stmt *_handle;
317
297
 
 
298
private:
 
299
 
318
300
        /** index used when auto-binding */
319
301
        unsigned int _bind_index;
320
302
 
321
303
};
322
304
 
323
305
 
324
 
// template specialisations for basic_statement::operator <<()
 
306
// template specialisations for statement::operator <<()
325
307
template< >
326
308
basic_statement &basic_statement::operator << < detail::null_t >(
327
309
        const detail::null_t & );
328
310
template< >
 
311
basic_statement &basic_statement::operator << < detail::exec_t >(
 
312
        const detail::exec_t & );
 
313
template< >
329
314
basic_statement &basic_statement::operator << < detail::set_index_t >(
330
315
        const detail::set_index_t &t );
331
316
 
332
317
 
333
 
} // namespace detail
334
 
 
335
 
 
336
318
} // namespace sqlite
337
319
 
338
320