4
* Copyright (C) 2009 Tim Marston <edam@waxworlds.org>
4
* Copyright (C) 2009 Tim Marston <tim@ed.am>
6
6
* This file is part of sqlite3cc (hereafter referred to as "this program").
7
* See http://www.waxworlds.org/edam/software/sqlite3cc for more information.
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.
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.
7
* See http://ed.am/dev/sqlite3cc for more information.
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
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
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/>.
45
* The statement class represents an SQL statement. It is the base class for
51
* The statement class represents an SQL statement. It is the base class for
46
52
* both the command and the query classes, which should be used for those
47
* purposes. The basic_statement class its self has protected instantiation.
53
* purposes. The basic_statement class its self has protected instantiation.
49
55
class basic_statement
58
* Constructor that provides a database upon which to act and the SQL
64
* Constructor that provides a connection upon which to act and the SQL
60
* @param database a reference to a database
67
* @param connection a reference to a connection
61
68
* @param sql an SQL statement in UTF-8
63
70
explicit basic_statement(
71
connection &connection,
65
72
const std::string &sql );
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
75
* Constructor that provides a connection upon which to act.
77
* @param connection a reference to a connection
72
79
explicit basic_statement(
80
connection &connection );
75
virtual ~basic_statement() throw( );
82
virtual ~basic_statement();
77
84
//______________________________________________________________________________
78
85
// public interface
88
96
const std::string &sql );
91
* Reset the statement, ready to re-execute it. This does not clear any of
99
* Reset the statement, ready to re-execute it. This does not clear any of
92
100
* the values bound to the statement.
93
102
* @returns an sqlite error code
94
103
* @see sqlite3_reset()
99
108
* Clears the values bound to a statement to NULL.
100
110
* @returns an sqlite error code
101
111
* @see sqlite3_clear_bindings()
103
113
int clear_bindings();
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
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
108
118
* internally stores the data anyway, so always binding as text just means
109
119
* we do the conversion instead of sqlite and is no less efficient.
110
121
* @param index the index of the parameter to bind to
111
122
* @param value the value to bind
112
123
* @returns an sqlite error code
126
137
* Bind a string value to the SQL statement via it's index where the value
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
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
130
142
* @param index the index of the parameter to bind to
131
143
* @param value the invariant string value
144
* @param value_length the length of the string including zero-terminator
132
145
* @returns an sqlite error code
133
146
* @see sqlite3_bind_text()
141
154
* Bind a string value to the SQL statement via it's index where the value
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
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
145
159
* @param index the index of the parameter to bind to
146
160
* @param value the invariant string value
147
161
* @returns an sqlite error code
155
169
* Bind a string value to the SQL statement via it's index where the value
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
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
159
174
* @param index the index of the parameter to bind to
160
175
* @param value the invariant string value
161
176
* @returns an sqlite error code
175
191
unsigned int index );
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
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
180
196
* sqlite internally stores the data anyway, so always binding as text just
181
197
* means we do the conversion instead of sqlite and is no less efficient.
182
199
* @param name the named parameter to bind to
183
200
* @param value the value to bind
184
201
* @returns an sqlite error code
196
213
* Bind a string value to the SQL statement via a named parameter where the
197
* string value will not change for the duration of the statement. This
198
* prevents a copy of the string being taken.
214
* string value will not change for the duration of the statement. This
215
* prevents sqlite from taking its own copy of the string.
199
217
* @param name the named parameter to bind to
200
218
* @param value the invariant string value
219
* @param value_length the length of the string including zero-terminator
201
220
* @returns an sqlite error code
202
221
* @see sqlite3_bind_text()
210
229
* Bind a string value to the SQL statement via a named parameter where the
211
* string value will not change for the duration of the statement. This
230
* string value will not change for the duration of the statement. This
212
231
* prevents a copy of the string being taken.
213
233
* @param name the named parameter to bind to
214
234
* @param value the invariant string value
215
235
* @returns an sqlite error code
223
243
* Bind a string value to the SQL statement via a named parameter where the
224
* string value will not change for the duration of the statement. This
244
* string value will not change for the duration of the statement. This
225
245
* prevents a copy of the string being taken.
226
247
* @param name the named parameter to bind to
227
248
* @param value the invariant string value
228
249
* @returns an sqlite error code
245
267
* Stream operator is used to bind values to parameters automatically, in
246
* ascending order. In addition, the null, set_index() and execute auto-
247
* binding manipulators can be used.
268
* ascending order. In addition, the null and set_index() auto-binding
269
* manipulators can be used.
248
271
* @param value a value to bind
250
273
template< class T >
251
274
basic_statement &operator <<(
254
int error_code = bind( _bind_index, value );
255
if( error_code != SQLITE_OK ) throw sqlite_error( error_code );
277
int code = bind( _bind_index, value );
278
if( code != SQLITE_OK ) throw sqlite_error( _connection, code );
267
290
* Finalise an SQL statement.
268
292
* @returns an sqlite error code
269
293
* @see sqlite3_finalize()
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()
283
* Get the index number of a named parameter
298
* Get the index number of a named parameter.
284
300
* @param parameter name
285
301
* @return index of named parameter
287
303
int bind_parameter_index(
288
304
const std::string &name );
290
/** the database upon which to act */
309
* @return sqlite error code
310
* @see sqlite3_step()
314
/** the connection upon which to act */
315
connection &_connection;
293
317
/** the statement handle */
294
318
sqlite3_stmt *_handle;
298
320
/** index used when auto-binding */
299
321
unsigned int _bind_index;
304
// template specialisations for statement::operator <<()
306
basic_statement &basic_statement::operator << < _null_t >(
309
basic_statement &basic_statement::operator << < _exec_t >(
312
basic_statement &basic_statement::operator << < _set_index_t >(
313
const _set_index_t &t );
326
// template specialisations for basic_statement::operator <<()
328
basic_statement &basic_statement::operator << < detail::null_t >(
329
const detail::null_t & );
331
basic_statement &basic_statement::operator << < detail::set_index_t >(
332
const detail::set_index_t &t );
335
} // namespace detail
316
338
} // namespace sqlite