/sqlite3cc : revision 1

1

/*

2

* statement.hpp

3

*

4

5

*

6

* This file is part of sqlitepp (hereafter referred to as "this program").

7

* See http://www.waxworlds.org/edam/software/sqlitepp 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

*

19

* You should have received a copy of the GNU Lesser General Public License

20

* along with this program. If not, see <http://www.gnu.org/licenses/>.

21

*/

22

23

#ifndef STATEMENT_HPP_

24

#define STATEMENT_HPP_

25

26

27

#include <sqlite3.h>

28

#include <boost/utility.hpp>

29

#include <boost/lexical_cast.hpp>

30

#include <sqlitepp/exception.hpp>

31

32

33

namespace sqlite

34

{

35

36

37

class database;

38

39

40

struct _null_t { };

41

struct _exec_t { };

42

struct _set_index_t { unsigned int _index; };

43

44

/**

45

* Auto-binding manipulator, for use with a statment's stream operator. This

46

* specifies a NULL value to bind to a parameter.

47

*/

48

extern const _null_t null;

49

50

/**

51

* Auto-binding manipulator, for use with a statment's stream operator. This

52

* indicates that the statement should be executed immediately. Unlike a

53

* statment's exec() method, this will throw on error. Also, it will throw if

54

* the execution returns any result rows.

55

*/

56

extern const _exec_t exec;

57

58

/**

59

* Auto-binding manipulator, for use with a statment's stream operator. This

60

* manipulator sets the index used to automatically assign values to parameters.

61

* @param index the new index for incremental assignment

62

*/

63

_set_index_t set_index(

64

unsigned int index );

65

66

67

/**

68

* The statement class represents an SQL statement. It is the bas class for both

69

* the command and the query classes which should be used for those purposes.

70

* The statement class its self has protected instantiation.

71

*/

72

class statement

73

:

74

private boost::noncopyable

75

{

76

//______________________________________________________________________________

77

// instantiation

78

protected:

79

80

/**

81

* Constructor that provides a database upon which to act and the SQL

82

* statement.

83

* @param database a reference to the database

84

* @param sql an SQL statement in UTF-8

85

*/

86

statement(

87

database &database,

88

const std::string &sql );

89

90

virtual ~statement() throw( );

91

92

//______________________________________________________________________________

93

// public interface

94

public:

95

96

/**

97

* Prepare an SQL statement.

98

* @param sql an SQL statement in UTF-8

99

* @returns an sqlite error code

100

* @see sqlite3_prepare_v2()

101

*/

102

int prepare(

103

const std::string &sql );

104

105

/**

106

* Step through one execution cycle of the SQL statement. If this is an SQL

107

* statement that doesn't return any rows, only one cycle is required,

108

* otherwise, each cycle will return another row

109

* @return an sqlite error code

110

* @see sqlite3_step()

111

*/

112

int step();

113

114

/**

115

* Reset the statement, ready to re-execute it. This does not clear any of

116

* the values bound to the statement.

117

* @returns an sqlite error code

118

* @see sqlite3_reset()

119

*/

120

int reset();

121

122

/**

123

* Clears the values bound to a statement to NULL.

124

* @returns an sqlite error code

125

* @see sqlite3_clear_bindings()

126

*/

127

int clear_bindings();

128

129

/**

130

* Bind a value to the SQL statement via it's index. This template will take

131

* a variety of data types and bind them as text. This is how sqlite

132

* internally stores the data anyway, so always binding as text just means

133

* we do the conversion instead of sqlite and is no less efficient.

134

* @param index the index of the parameter to bind to

135

* @param value the value to bind

136

* @returns an sqlite error code

137

* @see sqlite3_bind_text()

138

*/

139

template< class T >

140

int bind(

141

unsigned int index,

142

T value )

143

{

144

std::string string_value = boost::lexical_cast< std::string >( value );

145

return sqlite3_bind_text( _handle, index, string_value.c_str(),

146

string_value.length(), SQLITE_TRANSIENT );

147

}

148

149

/**

150

* Bind a string value to the SQL statement via it's index where the value

151

* of that string will not change for the duration of the statement. This is

152

* more optimal because sqlite will not have to make it's own copy of the

153

* data.

154

* @param index the index of the parameter to bind to

155

* @param value the invariant string value

156

* @returns an sqlite error code

157

* @see sqlite3_bind_text()

158

*/

159

int bind_static(

160

unsigned int index,

161

const char *value,

162

unsigned int value_length );

163

164

/**

165

* Bind a string value to the SQL statement via it's index where the value

166

* of that string will not change for the duration of the statement. This is

167

* more optimal because sqlite will not have to make it's own copy of the

168

* data.

169

* @param index the index of the parameter to bind to

170

* @param value the invariant string value

171

* @returns an sqlite error code

172

* @see sqlite3_bind_text()

173

*/

174

int bind_static(

175

unsigned int index,

176

const char *value );

177

178

/**

179

* Bind a string value to the SQL statement via it's index where the value

180

* of that string will not change for the duration of the statement. This is

181

* more optimal because sqlite will not have to make it's own copy of the

182

* data.

183

* @param index the index of the parameter to bind to

184

* @param value the invariant string value

185

* @returns an sqlite error code

186

* @see sqlite3_bind_text()

187

*/

188

int bind_static(

189

unsigned int index,

190

const std::string &value );

191

192

/**

193

* Bind a NULL value to the SQL statement via it's index.

194

* @param index the index of the parameter to bind to

195

* @returns an sqlite error code

196

* @see sqlite3_bind_null()

197

*/

198

int bind_null(

199

unsigned int index );

200

201

/**

202

* Bind a value to the SQL statement via a named parameter. This template

203

* will take a variety of data types and bind them as text. This is how

204

* sqlite internally stores the data anyway, so always binding as text just

205

* means we do the conversion instead of sqlite and is no less efficient.

206

* @param name the named parameter to bind to

207

* @param value the value to bind

208

* @returns an sqlite error code

209

* @see sqlite3_bind_text()

210

*/

211

template< class T >

212

int bind(

213

const std::string &name,

214

T value )

215

{

216

unsigned int index =

217

sqlite3_bind_parameter_index( _handle, name.c_str() );

218

return bind( index, value );

219

}

220

221

/**

222

* Bind a string value to the SQL statement via a named parameter where the

223

* string value will not change for the duration of the statement. This

224

* prevents a copy of the string being taken.

225

* @param name the named parameter to bind to

226

* @param value the invariant string value

227

* @returns an sqlite error code

228

* @see sqlite3_bind_text()

229

*/

230

int bind_static(

231

const std::string &name,

232

const char *value,

233

unsigned int value_length );

234

235

/**

236

* Bind a string value to the SQL statement via a named parameter where the

237

* string value will not change for the duration of the statement. This

238

* prevents a copy of the string being taken.

239

* @param name the named parameter to bind to

240

* @param value the invariant string value

241

* @returns an sqlite error code

242

* @see sqlite3_bind_text()

243

*/

244

int bind_static(

245

const std::string &name,

246

const char *value );

247

248

/**

249

* Bind a string value to the SQL statement via a named parameter where the

250

* string value will not change for the duration of the statement. This

251

* prevents a copy of the string being taken.

252

* @param name the named parameter to bind to

253

* @param value the invariant string value

254

* @returns an sqlite error code

255

* @see sqlite3_bind_text()

256

*/

257

int bind_static(

258

const std::string &name,

259

const std::string &value );

260

261

/**

262

* Bind a NULL value to the SQL statement via a named parameter.

263

* @param name the named parameter to bind to

264

* @returns an sqlite error code

265

* @see sqlite3_bind_null()

266

*/

267

int bind_null(

268

const std::string &name );

269

270

/**

271

* Stream operator is used to bind values to parameters automatically, in

272

* ascending order. In addition, the null, execute and set_index() auto-

273

* binding manipulators can be used.

274

* @param value a value to bind

275

*/

276

template< class T >

277

statement &operator <<( T value )

278

{

279

int error_code = bind( _bind_index, value );

280

if( error_code != SQLITE_OK ) throw sqlite_error( error_code );

281

_bind_index++;

282

return *this;

283

}

284

285

//______________________________________________________________________________

286

// implementation

287

protected:

288

289

/**

290

* Finalise an SQL statement.

291

* @returns an sqlite error code

292

* @see sqlite3_finalize()

293

*/

294

int finalize();

295

296

private:

297

298

/** the database upon which to act */

299

database &_database;

300

301

/** the statement handle */

302

sqlite3_stmt *_handle;

303

304

/** index used when auto-binding */

305

unsigned int _bind_index;

306

307

};

308

309

310

// template specialisations for statement::operator <<()

311

template< >

312

statement& statement::operator << < _null_t >(

313

_null_t );

314

template< >

315

statement& statement::operator << < _exec_t >(

316

_exec_t );

317

template< >

318

statement& statement::operator << < _set_index_t >(

319

_set_index_t t );

320

321

322

}

323

324

325

#endif /* STATEMENT_HPP_ */