4
* Copyright (C) 2009 Tim Marston <tim@ed.am>
4
* Copyright (C) 2009 Tim Marston <edam@waxworlds.org>
6
6
* This file is part of sqlite3cc (hereafter referred to as "this program").
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
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.
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/>.
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.
55
51
class basic_statement
64
* 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
67
* @param connection a reference to a connection
62
* @param database a reference to a database
68
63
* @param sql an SQL statement in UTF-8
70
65
explicit basic_statement(
71
connection &connection,
72
67
const std::string &sql );
75
* Constructor that provides a connection upon which to act.
77
* @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
79
74
explicit basic_statement(
80
connection &connection );
82
77
virtual ~basic_statement();
96
90
const std::string &sql );
99
* 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
100
94
* the values bound to the statement.
102
95
* @returns an sqlite error code
103
96
* @see sqlite3_reset()
108
101
* Clears the values bound to a statement to NULL.
110
102
* @returns an sqlite error code
111
103
* @see sqlite3_clear_bindings()
113
105
int clear_bindings();
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
* 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
118
110
* internally stores the data anyway, so always binding as text just means
119
111
* we do the conversion instead of sqlite and is no less efficient.
121
112
* @param index the index of the parameter to bind to
122
113
* @param value the value to bind
123
114
* @returns an sqlite error code
137
128
* 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
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
142
132
* @param index the index of the parameter to bind to
143
133
* @param value the invariant string value
144
* @param value_length the length of the string including zero-terminator
145
134
* @returns an sqlite error code
146
135
* @see sqlite3_bind_text()
154
143
* 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
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
159
147
* @param index the index of the parameter to bind to
160
148
* @param value the invariant string value
161
149
* @returns an sqlite error code
169
157
* 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
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
174
161
* @param index the index of the parameter to bind to
175
162
* @param value the invariant string value
176
163
* @returns an sqlite error code
191
177
unsigned int index );
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
* 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
196
182
* sqlite internally stores the data anyway, so always binding as text just
197
183
* means we do the conversion instead of sqlite and is no less efficient.
199
184
* @param name the named parameter to bind to
200
185
* @param value the value to bind
201
186
* @returns an sqlite error code
213
198
* 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.
199
* string value will not change for the duration of the statement. This
200
* prevents a copy of the string being taken.
217
201
* @param name the named parameter to bind to
218
202
* @param value the invariant string value
219
* @param value_length the length of the string including zero-terminator
220
203
* @returns an sqlite error code
221
204
* @see sqlite3_bind_text()
229
212
* 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
213
* string value will not change for the duration of the statement. This
231
214
* prevents a copy of the string being taken.
233
215
* @param name the named parameter to bind to
234
216
* @param value the invariant string value
235
217
* @returns an sqlite error code
243
225
* 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
226
* string value will not change for the duration of the statement. This
245
227
* prevents a copy of the string being taken.
247
228
* @param name the named parameter to bind to
248
229
* @param value the invariant string value
249
230
* @returns an sqlite error code
267
247
* 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.
248
* ascending order. In addition, the null, set_index() and execute auto-
249
* binding manipulators can be used.
271
250
* @param value a value to bind
273
252
template< class T >
274
253
basic_statement &operator <<(
277
int code = bind( _bind_index, value );
278
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 );
290
269
* Finalise an SQL statement.
292
270
* @returns an sqlite error code
293
271
* @see sqlite3_finalize()
298
* Get the index number of a named parameter.
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()
285
* Get the index number of a named parameter
300
286
* @param parameter name
301
287
* @return index of named parameter
303
289
int bind_parameter_index(
304
290
const std::string &name );
309
* @return sqlite error code
310
* @see sqlite3_step()
314
/** the connection upon which to act */
315
connection &_connection;
292
/** the database upon which to act */
317
295
/** the statement handle */
318
296
sqlite3_stmt *_handle;
320
300
/** index used when auto-binding */
321
301
unsigned int _bind_index;
326
// template specialisations for basic_statement::operator <<()
306
// template specialisations for statement::operator <<()
328
308
basic_statement &basic_statement::operator << < detail::null_t >(
329
309
const detail::null_t & );
311
basic_statement &basic_statement::operator << < detail::exec_t >(
312
const detail::exec_t & );
331
314
basic_statement &basic_statement::operator << < detail::set_index_t >(
332
315
const detail::set_index_t &t );
335
} // namespace detail
338
318
} // namespace sqlite