/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: 2011-12-05 19:44:14 UTC
  • Revision ID: edam@waxworlds.org-20111205194414-mj9yzdnf8h5kzhmp
updaed TODO, fixed a comment

Show diffs side-by-side

added added

removed removed

Lines of Context:
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/>.
48
48
 
49
49
 
50
50
/**
51
 
 * 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
52
52
 * both the command and the query classes, which should be used for those
53
 
 * purposes.  The basic_statement class its self has protected instantiation.
 
53
 * purposes. The basic_statement class its self has protected instantiation.
54
54
 */
55
55
class basic_statement
 
56
        :
 
57
        private boost::noncopyable
56
58
{
57
59
//______________________________________________________________________________
58
60
//                                                                 instantiation
61
63
        /**
62
64
         * Constructor that provides a connection upon which to act and the SQL
63
65
         * statement.
64
 
         *
65
66
         * @param connection a reference to a connection
66
67
         * @param sql an SQL statement in UTF-8
67
68
         */
71
72
 
72
73
        /**
73
74
         * Constructor that provides a connection upon which to act.
74
 
         *
75
75
         * @param connection a reference to a connection
76
76
         */
77
77
        explicit basic_statement(
85
85
 
86
86
        /**
87
87
         * Prepare an SQL statement.
88
 
         *
89
88
         * @param sql an SQL statement in UTF-8
90
89
         * @returns an sqlite error code
91
90
         * @see sqlite3_prepare_v2()
94
93
                const std::string &sql );
95
94
 
96
95
        /**
97
 
         * Reset the statement, ready to re-execute it.  This does not clear any of
 
96
         * Reset the statement, ready to re-execute it. This does not clear any of
98
97
         * the values bound to the statement.
99
 
         *
100
98
         * @returns an sqlite error code
101
99
         * @see sqlite3_reset()
102
100
         */
104
102
 
105
103
        /**
106
104
         * Clears the values bound to a statement to NULL.
107
 
         *
108
105
         * @returns an sqlite error code
109
106
         * @see sqlite3_clear_bindings()
110
107
         */
111
108
        int clear_bindings();
112
109
 
113
110
        /**
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
 
111
         * Bind a value to the SQL statement via it's index. This template will take
 
112
         * a variety of data types and bind them as text. This is how sqlite
116
113
         * internally stores the data anyway, so always binding as text just means
117
114
         * we do the conversion instead of sqlite and is no less efficient.
118
 
         *
119
115
         * @param index the index of the parameter to bind to
120
116
         * @param value the value to bind
121
117
         * @returns an sqlite error code
133
129
 
134
130
        /**
135
131
         * 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
 
132
         * of that string will not change for the duration of the statement. This is
 
133
         * more optimal because sqlite will not have to take it's own copy of the
138
134
         * data.
139
 
         *
140
135
         * @param index the index of the parameter to bind to
141
136
         * @param value the invariant string value
142
137
         * @param value_length the length of the string including zero-terminator
150
145
 
151
146
        /**
152
147
         * 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
 
148
         * of that string will not change for the duration of the statement. This is
 
149
         * more optimal  because sqlite will not have to take it's own copy of the
155
150
         * data.
156
 
         *
157
151
         * @param index the index of the parameter to bind to
158
152
         * @param value the invariant string value
159
153
         * @returns an sqlite error code
165
159
 
166
160
        /**
167
161
         * 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
 
162
         * of that string will not change for the duration of the statement. This is
 
163
         * more optimal because sqlite will not have to take it's own copy of the
170
164
         * data.
171
 
         *
172
165
         * @param index the index of the parameter to bind to
173
166
         * @param value the invariant string value
174
167
         * @returns an sqlite error code
180
173
 
181
174
        /**
182
175
         * Bind a NULL value to the SQL statement via it's index.
183
 
         *
184
176
         * @param index the index of the parameter to bind to
185
177
         * @returns an sqlite error code
186
178
         * @see sqlite3_bind_null()
189
181
                unsigned int index );
190
182
 
191
183
        /**
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
 
184
         * Bind a value to the SQL statement via a named parameter. This template
 
185
         * will take a variety of data types and bind them as text. This is how
194
186
         * sqlite internally stores the data anyway, so always binding as text just
195
187
         * means we do the conversion instead of sqlite and is no less efficient.
196
 
         *
197
188
         * @param name the named parameter to bind to
198
189
         * @param value the value to bind
199
190
         * @returns an sqlite error code
209
200
 
210
201
        /**
211
202
         * 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
 
203
         * string value will not change for the duration of the statement. This
213
204
         * prevents sqlite from taking its own copy of the string.
214
 
         *
215
205
         * @param name the named parameter to bind to
216
206
         * @param value the invariant string value
217
207
         * @param value_length the length of the string including zero-terminator
225
215
 
226
216
        /**
227
217
         * 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
 
218
         * string value will not change for the duration of the statement. This
229
219
         * prevents a copy of the string being taken.
230
 
         *
231
220
         * @param name the named parameter to bind to
232
221
         * @param value the invariant string value
233
222
         * @returns an sqlite error code
239
228
 
240
229
        /**
241
230
         * 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
 
231
         * string value will not change for the duration of the statement. This
243
232
         * prevents a copy of the string being taken.
244
 
         *
245
233
         * @param name the named parameter to bind to
246
234
         * @param value the invariant string value
247
235
         * @returns an sqlite error code
253
241
 
254
242
        /**
255
243
         * Bind a NULL value to the SQL statement via a named parameter.
256
 
         *
257
244
         * @param name the named parameter to bind to
258
245
         * @returns an sqlite error code
259
246
         * @see sqlite3_bind_null()
263
250
 
264
251
        /**
265
252
         * Stream operator is used to bind values to parameters automatically, in
266
 
         * ascending order.  In addition, the null and set_index() auto-binding
 
253
         * ascending order. In addition, the null and set_index() auto-binding
267
254
         * manipulators can be used.
268
 
         *
269
255
         * @param value a value to bind
270
256
         */
271
257
        template< class T >
286
272
 
287
273
        /**
288
274
         * Finalise an SQL statement.
289
 
         *
290
275
         * @returns an sqlite error code
291
276
         * @see sqlite3_finalize()
292
277
         */
293
278
        int finalize();
294
279
 
295
280
        /**
296
 
         * Get the index number of a named parameter.
297
 
         *
 
281
         * Get the index number of a named parameter
298
282
         * @param parameter name
299
283
         * @return index of named parameter
300
284
         */
302
286
                const std::string &name );
303
287
 
304
288
        /**
305
 
         * Perform a step.
306
 
         *
 
289
         * Perform a step
307
290
         * @return sqlite error code
308
291
         * @see sqlite3_step()
309
292
         */