/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-03-09 14:06:50 UTC
  • Revision ID: edam@waxworlds.org-20100309140650-oqwnsrbajh8d2p2m
- moved dependancy on boost_filesystem-mt from the library to test-main

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
 
namespace detail {
40
 
        struct null_t;
41
 
        struct exec_t;
42
 
        struct set_index_t;
43
 
}
44
 
 
45
 
 
46
 
namespace detail
47
 
{
 
39
struct _null_t;
 
40
struct _exec_t;
 
41
struct _set_index_t;
48
42
 
49
43
 
50
44
/**
51
 
 * The statement class represents an SQL statement.  It is the base class for
 
45
 * The statement class represents an SQL statement. It is the base class for
52
46
 * both the command and the query classes, which should be used for those
53
 
 * purposes.  The basic_statement class its self has protected instantiation.
 
47
 * purposes. The basic_statement class its self has protected instantiation.
54
48
 */
55
49
class basic_statement
56
50
        :
61
55
protected:
62
56
 
63
57
        /**
64
 
         * Constructor that provides a connection upon which to act and the SQL
 
58
         * Constructor that provides a database upon which to act and the SQL
65
59
         * statement.
66
 
         *
67
 
         * @param connection a reference to a connection
 
60
         * @param database a reference to a database
68
61
         * @param sql an SQL statement in UTF-8
69
62
         */
70
63
        explicit basic_statement(
71
 
                connection &connection,
 
64
                database &database,
72
65
                const std::string &sql );
73
66
 
74
67
        /**
75
 
         * Constructor that provides a connection upon which to act.
76
 
         *
77
 
         * @param connection a reference to a connection
 
68
         * Constructor that provides a database upon which to act.
 
69
         * @param database a reference to a database
 
70
         * @param sql an SQL statement in UTF-8
78
71
         */
79
72
        explicit basic_statement(
80
 
                connection &connection );
 
73
                database &database );
81
74
 
82
 
        virtual ~basic_statement();
 
75
        virtual ~basic_statement() throw( );
83
76
 
84
77
//______________________________________________________________________________
85
78
//                                                              public interface
87
80
 
88
81
        /**
89
82
         * Prepare an SQL statement.
90
 
         *
91
83
         * @param sql an SQL statement in UTF-8
92
84
         * @returns an sqlite error code
93
85
         * @see sqlite3_prepare_v2()
96
88
                const std::string &sql );
97
89
 
98
90
        /**
99
 
         * Reset the statement, ready to re-execute it.  This does not clear any of
 
91
         * Reset the statement, ready to re-execute it. This does not clear any of
100
92
         * the values bound to the statement.
101
 
         *
102
93
         * @returns an sqlite error code
103
94
         * @see sqlite3_reset()
104
95
         */
105
 
        virtual int reset();
 
96
        int reset();
106
97
 
107
98
        /**
108
99
         * Clears the values bound to a statement to NULL.
109
 
         *
110
100
         * @returns an sqlite error code
111
101
         * @see sqlite3_clear_bindings()
112
102
         */
113
103
        int clear_bindings();
114
104
 
115
105
        /**
116
 
         * Bind a value to the SQL statement via it's index.  This template will
117
 
         * take a variety of data types and bind them as text.  This is how sqlite
 
106
         * Bind a value to the SQL statement via it's index. This template will take
 
107
         * a variety of data types and bind them as text. This is how sqlite
118
108
         * internally stores the data anyway, so always binding as text just means
119
109
         * we do the conversion instead of sqlite and is no less efficient.
120
 
         *
121
110
         * @param index the index of the parameter to bind to
122
111
         * @param value the value to bind
123
112
         * @returns an sqlite error code
135
124
 
136
125
        /**
137
126
         * Bind a string value to the SQL statement via it's index where the value
138
 
         * of that string will not change for the duration of the statement.  This
139
 
         * is more optimal because sqlite will not have to take it's own copy of the
 
127
         * of that string will not change for the duration of the statement. This is
 
128
         * more optimal because sqlite will not have to make it's own copy of the
140
129
         * data.
141
 
         *
142
130
         * @param index the index of the parameter to bind to
143
131
         * @param value the invariant string value
144
 
         * @param value_length the length of the string including zero-terminator
145
132
         * @returns an sqlite error code
146
133
         * @see sqlite3_bind_text()
147
134
         */
152
139
 
153
140
        /**
154
141
         * Bind a string value to the SQL statement via it's index where the value
155
 
         * of that string will not change for the duration of the statement.  This
156
 
         * is more optimal because sqlite will not have to take it's own copy of the
 
142
         * of that string will not change for the duration of the statement. This is
 
143
         * more optimal  because sqlite will not have to make it's own copy of the
157
144
         * data.
158
 
         *
159
145
         * @param index the index of the parameter to bind to
160
146
         * @param value the invariant string value
161
147
         * @returns an sqlite error code
167
153
 
168
154
        /**
169
155
         * Bind a string value to the SQL statement via it's index where the value
170
 
         * of that string will not change for the duration of the statement.  This
171
 
         * is more optimal because sqlite will not have to take it's own copy of the
 
156
         * of that string will not change for the duration of the statement. This is
 
157
         * more optimal because sqlite will not have to make it's own copy of the
172
158
         * data.
173
 
         *
174
159
         * @param index the index of the parameter to bind to
175
160
         * @param value the invariant string value
176
161
         * @returns an sqlite error code
182
167
 
183
168
        /**
184
169
         * Bind a NULL value to the SQL statement via it's index.
185
 
         *
186
170
         * @param index the index of the parameter to bind to
187
171
         * @returns an sqlite error code
188
172
         * @see sqlite3_bind_null()
191
175
                unsigned int index );
192
176
 
193
177
        /**
194
 
         * Bind a value to the SQL statement via a named parameter.  This template
195
 
         * will take a variety of data types and bind them as text.  This is how
 
178
         * Bind a value to the SQL statement via a named parameter. This template
 
179
         * will take a variety of data types and bind them as text. This is how
196
180
         * sqlite internally stores the data anyway, so always binding as text just
197
181
         * means we do the conversion instead of sqlite and is no less efficient.
198
 
         *
199
182
         * @param name the named parameter to bind to
200
183
         * @param value the value to bind
201
184
         * @returns an sqlite error code
211
194
 
212
195
        /**
213
196
         * Bind a string value to the SQL statement via a named parameter where the
214
 
         * string value will not change for the duration of the statement.  This
215
 
         * prevents sqlite from taking its own copy of the string.
216
 
         *
 
197
         * string value will not change for the duration of the statement. This
 
198
         * prevents a copy of the string being taken.
217
199
         * @param name the named parameter to bind to
218
200
         * @param value the invariant string value
219
 
         * @param value_length the length of the string including zero-terminator
220
201
         * @returns an sqlite error code
221
202
         * @see sqlite3_bind_text()
222
203
         */
227
208
 
228
209
        /**
229
210
         * Bind a string value to the SQL statement via a named parameter where the
230
 
         * string value will not change for the duration of the statement.  This
 
211
         * string value will not change for the duration of the statement. This
231
212
         * prevents a copy of the string being taken.
232
 
         *
233
213
         * @param name the named parameter to bind to
234
214
         * @param value the invariant string value
235
215
         * @returns an sqlite error code
241
221
 
242
222
        /**
243
223
         * Bind a string value to the SQL statement via a named parameter where the
244
 
         * string value will not change for the duration of the statement.  This
 
224
         * string value will not change for the duration of the statement. This
245
225
         * prevents a copy of the string being taken.
246
 
         *
247
226
         * @param name the named parameter to bind to
248
227
         * @param value the invariant string value
249
228
         * @returns an sqlite error code
255
234
 
256
235
        /**
257
236
         * Bind a NULL value to the SQL statement via a named parameter.
258
 
         *
259
237
         * @param name the named parameter to bind to
260
238
         * @returns an sqlite error code
261
239
         * @see sqlite3_bind_null()
265
243
 
266
244
        /**
267
245
         * Stream operator is used to bind values to parameters automatically, in
268
 
         * ascending order.  In addition, the null and set_index() auto-binding
269
 
         * manipulators can be used.
270
 
         *
 
246
         * ascending order. In addition, the null, set_index() and execute auto-
 
247
         * binding manipulators can be used.
271
248
         * @param value a value to bind
272
249
         */
273
250
        template< class T >
274
251
        basic_statement &operator <<(
275
252
                const T &value )
276
253
        {
277
 
                int code = bind( _bind_index, value );
278
 
                if( code != SQLITE_OK ) throw sqlite_error( _connection, code );
 
254
                int error_code = bind( _bind_index, value );
 
255
                if( error_code != SQLITE_OK ) throw sqlite_error( error_code );
279
256
                _bind_index++;
280
257
                return *this;
281
258
        }
288
265
 
289
266
        /**
290
267
         * Finalise an SQL statement.
291
 
         *
292
268
         * @returns an sqlite error code
293
269
         * @see sqlite3_finalize()
294
270
         */
295
271
        int finalize();
296
272
 
297
273
        /**
298
 
         * Get the index number of a named parameter.
299
 
         *
 
274
         * Step through one execution cycle of the SQL statement. If this is an SQL
 
275
         * statement that doesn't return any rows, only one cycle is required,
 
276
         * otherwise, each cycle will return another row
 
277
         * @return an sqlite error code
 
278
         * @see sqlite3_step()
 
279
         */
 
280
        int step();
 
281
 
 
282
        /**
 
283
         * Get the index number of a named parameter
300
284
         * @param parameter name
301
285
         * @return index of named parameter
302
286
         */
303
287
        int bind_parameter_index(
304
288
                const std::string &name );
305
289
 
306
 
        /**
307
 
         * Perform a step.
308
 
         *
309
 
         * @return sqlite error code
310
 
         * @see sqlite3_step()
311
 
         */
312
 
        int step();
313
 
 
314
 
        /** the connection upon which to act */
315
 
        connection &_connection;
 
290
        /** the database upon which to act */
 
291
        database &_database;
316
292
 
317
293
        /** the statement handle */
318
294
        sqlite3_stmt *_handle;
319
295
 
 
296
private:
 
297
 
320
298
        /** index used when auto-binding */
321
299
        unsigned int _bind_index;
322
300
 
323
301
};
324
302
 
325
303
 
326
 
// template specialisations for basic_statement::operator <<()
327
 
template< >
328
 
basic_statement &basic_statement::operator << < detail::null_t >(
329
 
        const detail::null_t & );
330
 
template< >
331
 
basic_statement &basic_statement::operator << < detail::set_index_t >(
332
 
        const detail::set_index_t &t );
333
 
 
334
 
 
335
 
} // namespace detail
 
304
// template specialisations for statement::operator <<()
 
305
template< >
 
306
basic_statement &basic_statement::operator << < _null_t >(
 
307
        const _null_t & );
 
308
template< >
 
309
basic_statement &basic_statement::operator << < _exec_t >(
 
310
        const _exec_t & );
 
311
template< >
 
312
basic_statement &basic_statement::operator << < _set_index_t >(
 
313
        const _set_index_t &t );
336
314
 
337
315
 
338
316
} // namespace sqlite