/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: 2012-01-23 13:46:27 UTC
  • Revision ID: edam@waxworlds.org-20120123134627-i6hi9aftfvwgp8vw
updated autotols stuff

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
56
        :
63
63
        /**
64
64
         * Constructor that provides a connection upon which to act and the SQL
65
65
         * statement.
66
 
         *
67
66
         * @param connection a reference to a connection
68
67
         * @param sql an SQL statement in UTF-8
69
68
         */
73
72
 
74
73
        /**
75
74
         * Constructor that provides a connection upon which to act.
76
 
         *
77
75
         * @param connection a reference to a connection
78
76
         */
79
77
        explicit basic_statement(
87
85
 
88
86
        /**
89
87
         * Prepare an SQL statement.
90
 
         *
91
88
         * @param sql an SQL statement in UTF-8
92
89
         * @returns an sqlite error code
93
90
         * @see sqlite3_prepare_v2()
96
93
                const std::string &sql );
97
94
 
98
95
        /**
99
 
         * 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
100
97
         * the values bound to the statement.
101
 
         *
102
98
         * @returns an sqlite error code
103
99
         * @see sqlite3_reset()
104
100
         */
106
102
 
107
103
        /**
108
104
         * Clears the values bound to a statement to NULL.
109
 
         *
110
105
         * @returns an sqlite error code
111
106
         * @see sqlite3_clear_bindings()
112
107
         */
113
108
        int clear_bindings();
114
109
 
115
110
        /**
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
 
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
118
113
         * internally stores the data anyway, so always binding as text just means
119
114
         * we do the conversion instead of sqlite and is no less efficient.
120
 
         *
121
115
         * @param index the index of the parameter to bind to
122
116
         * @param value the value to bind
123
117
         * @returns an sqlite error code
135
129
 
136
130
        /**
137
131
         * 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
 
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
140
134
         * data.
141
 
         *
142
135
         * @param index the index of the parameter to bind to
143
136
         * @param value the invariant string value
144
137
         * @param value_length the length of the string including zero-terminator
152
145
 
153
146
        /**
154
147
         * 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
 
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
157
150
         * data.
158
 
         *
159
151
         * @param index the index of the parameter to bind to
160
152
         * @param value the invariant string value
161
153
         * @returns an sqlite error code
167
159
 
168
160
        /**
169
161
         * 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
 
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
172
164
         * data.
173
 
         *
174
165
         * @param index the index of the parameter to bind to
175
166
         * @param value the invariant string value
176
167
         * @returns an sqlite error code
182
173
 
183
174
        /**
184
175
         * Bind a NULL value to the SQL statement via it's index.
185
 
         *
186
176
         * @param index the index of the parameter to bind to
187
177
         * @returns an sqlite error code
188
178
         * @see sqlite3_bind_null()
191
181
                unsigned int index );
192
182
 
193
183
        /**
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
 
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
196
186
         * sqlite internally stores the data anyway, so always binding as text just
197
187
         * means we do the conversion instead of sqlite and is no less efficient.
198
 
         *
199
188
         * @param name the named parameter to bind to
200
189
         * @param value the value to bind
201
190
         * @returns an sqlite error code
211
200
 
212
201
        /**
213
202
         * 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
 
203
         * string value will not change for the duration of the statement. This
215
204
         * prevents sqlite from taking its own copy of the string.
216
 
         *
217
205
         * @param name the named parameter to bind to
218
206
         * @param value the invariant string value
219
207
         * @param value_length the length of the string including zero-terminator
227
215
 
228
216
        /**
229
217
         * 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
 
218
         * string value will not change for the duration of the statement. This
231
219
         * prevents a copy of the string being taken.
232
 
         *
233
220
         * @param name the named parameter to bind to
234
221
         * @param value the invariant string value
235
222
         * @returns an sqlite error code
241
228
 
242
229
        /**
243
230
         * 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
 
231
         * string value will not change for the duration of the statement. This
245
232
         * prevents a copy of the string being taken.
246
 
         *
247
233
         * @param name the named parameter to bind to
248
234
         * @param value the invariant string value
249
235
         * @returns an sqlite error code
255
241
 
256
242
        /**
257
243
         * Bind a NULL value to the SQL statement via a named parameter.
258
 
         *
259
244
         * @param name the named parameter to bind to
260
245
         * @returns an sqlite error code
261
246
         * @see sqlite3_bind_null()
265
250
 
266
251
        /**
267
252
         * Stream operator is used to bind values to parameters automatically, in
268
 
         * ascending order.  In addition, the null and set_index() auto-binding
 
253
         * ascending order. In addition, the null and set_index() auto-binding
269
254
         * manipulators can be used.
270
 
         *
271
255
         * @param value a value to bind
272
256
         */
273
257
        template< class T >
288
272
 
289
273
        /**
290
274
         * Finalise an SQL statement.
291
 
         *
292
275
         * @returns an sqlite error code
293
276
         * @see sqlite3_finalize()
294
277
         */
295
278
        int finalize();
296
279
 
297
280
        /**
298
 
         * Get the index number of a named parameter.
299
 
         *
 
281
         * Get the index number of a named parameter
300
282
         * @param parameter name
301
283
         * @return index of named parameter
302
284
         */
304
286
                const std::string &name );
305
287
 
306
288
        /**
307
 
         * Perform a step.
308
 
         *
 
289
         * Perform a step
309
290
         * @return sqlite error code
310
291
         * @see sqlite3_step()
311
292
         */