#include <sq3.hpp>
Public Member Functions | |
statement (database &db) | |
Initializes a prepared statement without a query. | |
statement (database &db, std::string const &sql) | |
Initializes a statement with the given sql. | |
statement (database &db, char const *sql, int byteCount=-1) | |
Initializes a statement with the given sql. | |
~statement () | |
Calls this->finalize(). | |
int | prepare (std::string const &sql) |
(Re-)prepares an SQL statement. | |
int | prepare (char const *sql, int byteCount=-1) |
Same as prepare(std::string) but the len parameter specifies the length of sql. | |
int | bind (int index) |
Binds NULL to the given placeholder index (1-based, not 0-based!). | |
int | bind (int index, int data) |
Binds data to the given placeholder index (1-based, not 0-based!). | |
int | bind (int index, int64_t data) |
Binds data to the given placeholder index (1-based, not 0-based!). | |
int | bind (int index, double data) |
Binds data to the given placeholder index (1-based, not 0-based!). | |
int | bind (int index, char const *data, int len) |
Binds data to the given placeholder index (1-based, not 0-based!). | |
int | bind (int index, void const *data, int len) |
Binds data to the given placeholder index (1-based, not 0-based!). | |
int | bind (int index, std::string const &data) |
Binds data to the given placeholder index (1-based, not 0-based!). | |
int | bind (char const *index) |
Binds NULL to the given placeholder index. | |
int | bind (char const *index, int data) |
Binds data to the given placeholder index. | |
int | bind (char const *index, int64_t data) |
Binds data to the given placeholder index. | |
int | bind (char const *index, double data) |
Binds data to the given placeholder index. | |
int | bind (char const *index, char const *data, int len) |
Binds data to the given placeholder index. | |
int | bind (char const *index, void const *data, int len) |
Binds data to the given placeholder index. | |
int | bind (char const *index, std::string const &data) |
Binds data to the given placeholder index. | |
cursor | get_cursor () |
Returns a cursor object ready to step over the result set from this object. | |
int | execute () |
Assumes this object's SQL statement is a single statement. | |
int | execute (int &tgt) |
Executes this statement and saves the return value of that statement in tgt. | |
int | execute (int64_t &tgt) |
See execute(int&). | |
int | execute (double &tgt) |
See execute(int&). | |
int | execute (std::string &tgt) |
See execute(int&). | |
int | execute (sqlite3_text_char_t const **tgt, int &len) |
See execute(int&). | |
int | execute (void const **tgt, int &len) |
See execute(sqlite3_text_char_t const ,int&). | |
int | finalize () |
Finizalizes the underlying prepared statement, freeing its resources. | |
bool | is_prepared () const |
Use after construction to ensure that a statement was compiled. | |
int | reset () |
Calls sqlite3_reset() on the underlying statement handle and returns the result. | |
int | colcount () |
Returns the column count of this prepared statement, or -1 on error. | |
char const * | colname (int index) |
On success, it returns the null-terminated column name of the given column. | |
int | colname (int index, char const **cn) |
On success, assigns cn to the null-terminated column name at the given index and returns SQLITE_OK. | |
Friends | |
class | cursor |
statement objects are copied shallowly - each copy points back to a single original sqlite3_stmt object. That sqlite3_stmt is finalized with the last of these copies goes out of scope or is finalized.
Sample usage:
// Reading data: statement st(mydb, "select * from sqlite_master"); if( ! st.is_prepared() ) { ... error ... } cursor cur( st.get_cursor() ); while( SQLITE_ROW == cur.step() ) { ... do something with each row ... } // Or: statement st(mydb, "select count(*) from mytable" ); int val = 0; int rc = st.execute( val ); if( ! rc_is_okay( rc ) ) { ... error ... } std::cout << "count(*) == " << val << '\n'; // Writing data: statement st( mydb, "insert into mytable values(?,?)" ); st.bind( 1, "a value" ); st.bind( 2, someIntValue ); int rc = st.execute(); if( ! rc_is_okay( rc ) ) { ... error ... }
Note about copying: copying a statement object produces a shallow copy. All copies of this type will refer to the same underlying (sqlite3_stmt*) handle. The handle will be closed when the last instance of this class which points to that statement goes out of scope or is finalized.
Definition at line 973 of file sq3.hpp.
sq3::statement::statement | ( | database & | db | ) |
sq3::statement::statement | ( | database & | db, | |
std::string const & | sql | |||
) |
Initializes a statement with the given sql.
Use is_prepared() to determine if the sql compiled successfully.
Definition at line 140 of file sq3.cpp.
References prepare().
sq3::statement::statement | ( | database & | db, | |
char const * | sql, | |||
int | byteCount = -1 | |||
) |
Initializes a statement with the given sql.
Use is_prepared() to determine if the sql compiled successfully. byteCount is the length of sql, in bytes. If set to -1 then strlen() is used to determine the size of sql.
Definition at line 145 of file sq3.cpp.
References prepare().
int sq3::statement::bind | ( | char const * | index, | |
std::string const & | data | |||
) |
Binds data to the given placeholder index.
See bind(char const *) for more info.
Definition at line 237 of file sq3.cpp.
References bind().
int sq3::statement::bind | ( | char const * | index, | |
void const * | data, | |||
int | len | |||
) |
Binds data to the given placeholder index.
len must be the length of data, in bytes. See bind(char const *) for more info.
Definition at line 231 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | char const * | index, | |
char const * | data, | |||
int | len | |||
) |
Binds data to the given placeholder index.
len must be the length of data, in bytes. See bind(char const *) for more info.
Definition at line 225 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | char const * | index, | |
double | data | |||
) |
Binds data to the given placeholder index.
See bind(char const *) for more info.
Definition at line 220 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | char const * | index, | |
int64_t | data | |||
) |
Binds data to the given placeholder index.
See bind(char const *) for more info.
Definition at line 215 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | char const * | index, | |
int | data | |||
) |
Binds data to the given placeholder index.
See bind(char const *) for more info.
Definition at line 210 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | char const * | index | ) |
Binds NULL to the given placeholder index.
Note that binding by string index is notably less efficient than binding by integer index.
Named placeholders are embedded in SQL similar to:
INSERT INTO MyTable (a,b) VALUES(:A,:B);
In that string we have two named bound arguments: ":A" and ":B", at indexes 1 and 2, respectively. Note that the leading colon is considered to be part of the name.
Definition at line 205 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | int | index, | |
void const * | data, | |||
int | len | |||
) |
Binds data to the given placeholder index (1-based, not 0-based!).
len must be the length of data, in bytes.
Definition at line 194 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | int | index, | |
char const * | data, | |||
int | len | |||
) |
Binds data to the given placeholder index (1-based, not 0-based!).
len must be the length of data, in bytes.
Definition at line 189 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::bind | ( | int | index | ) |
Binds NULL to the given placeholder index (1-based, not 0-based!).
Placeholders are added to SQL code with question marks, like this:
INSERT INTO MyTable(a,b) VALUES(?,?);
In this case we have two placeholders at indexes 1 and 2.
Note that all bind()-related indexes are 1-based, but cursor::get() uses 0-based indexes. This inconsistency is an artefact of the sqlite3 API (and may even have a longer history).
Definition at line 173 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
Referenced by bind(), sq3::database::clear(), sq3::settings_db::get(), sq3::log_db::log(), and sq3::settings_db::set().
int sq3::statement::colcount | ( | ) |
Returns the column count of this prepared statement, or -1 on error.
May return 0 for queries which has no return value (e.g. UPDATE).
Definition at line 311 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
Referenced by colname().
int sq3::statement::colname | ( | int | index, | |
char const ** | cn | |||
) |
On success, assigns cn to the null-terminated column name at the given index and returns SQLITE_OK.
On failure cn is not modified and some other value is returned. The column name string is not guaranteed to be valid longer than this preparation of this statement object, so copy it immediately if you will need it later.
Definition at line 326 of file sq3.cpp.
References colname().
char const * sq3::statement::colname | ( | int | index | ) |
On success, it returns the null-terminated column name of the given column.
On error it returns 0. The returned string is owned by sqlite3 and is not guaranteed to be valid longer than the lifetime of this statement, so copy it if you need it.
Definition at line 318 of file sq3.cpp.
References colcount(), and refcount::rcptr< HandleT, FinalizerT >::get().
Referenced by colname().
int sq3::statement::execute | ( | void const ** | tgt, | |
int & | len | |||
) |
See execute(sqlite3_text_char_t const ,int&).
This is similar but is used to fetch blob data. The blob is "returned" by passinging tgt to it. The length of the blob (in bytes) is saved in len. Ownership of the blob data remains with sqlite3, and the client should copy it if he wants to ensure that he has it for later. The blob's exact lifetime is unspecified in the sqlite3 documentation, but in theory it is valid until this statement object is finalized or a cursor object steps through the result set of this statement.
Definition at line 292 of file sq3.cpp.
References sq3::cursor::get(), get_cursor(), and sq3::cursor::step().
int sq3::statement::execute | ( | sqlite3_text_char_t const ** | tgt, | |
int & | len | |||
) |
See execute(int&).
The length of the "returned" string is saved in len (in bytes). Ownership of the string remains with sqlite3, and the client should copy it if he wants to ensure that he has it for later. The string's exact lifetime is unspecified in the sqlite3 documentation, but in theory it is valid until this statement object is finalized or a cursor object steps through the result set of this statement.
Definition at line 282 of file sq3.cpp.
References sq3::cursor::get(), get_cursor(), and sq3::cursor::step().
int sq3::statement::execute | ( | std::string & | tgt | ) |
int sq3::statement::execute | ( | double & | tgt | ) |
int sq3::statement::execute | ( | int64_t & | tgt | ) |
int sq3::statement::execute | ( | int & | tgt | ) |
Executes this statement and saves the return value of that statement in tgt.
If this function returns any other value than SQLITE_OK then tgt is not modified. Note that the value of this object's first field must be lexically convertible to tgt's type or else tgt will be set to some unspecified value.
int sq3::statement::execute | ( | ) |
Assumes this object's SQL statement is a single statement.
Executes that statement and returns the value from an underlying sqlite3_step() call. Thus SQLITE_ROW or SQLITE_DONE will be returned on success, depending on the underlying query.
Definition at line 250 of file sq3.cpp.
References get_cursor(), and sq3::cursor::step().
Referenced by sq3::settings_db::get(), sq3::log_db::log(), and sq3::settings_db::set().
int sq3::statement::finalize | ( | ) |
Finizalizes the underlying prepared statement, freeing its resources.
Any cursor objects created through this->get_cursor() now points to stale data and must not be used.
Return value is the result of calling sqlite3_finalize(), or SQLITE_ERROR if finalization cannot take place (e.g. finalize() was already called).
Definition at line 122 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get(), and refcount::rcptr< HandleT, FinalizerT >::take().
Referenced by prepare(), and ~statement().
cursor sq3::statement::get_cursor | ( | ) |
Returns a cursor object ready to step over the result set from this object.
Note that due to low-level design details, it is unwise to mix the execute() functions and get_cursor() on the same statement. All cursors created from this statement (and all copies of those cursors) relate back to *this* statement object and when the last cursor goes out of scope the underlying prepared statement is reset. Additionally, the execute() family of functions are all actually implemented in terms of get_cursor(). Mis-interactions between a mixture of get_cursor() and execute() on the same client-side statement object cannot be ruled out.
See the ~cursor destructor for more details.
Definition at line 246 of file sq3.cpp.
Referenced by sq3::database::clear(), and execute().
bool sq3::statement::is_prepared | ( | ) | const |
Use after construction to ensure that a statement was compiled.
Returns true if the statement was compiled, else false. Returning false typically means that the supplied SQL has a syntax error, refers to non-existing fields, etc.
Definition at line 165 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::statement::prepare | ( | char const * | sql, | |
int | byteCount = -1 | |||
) |
Same as prepare(std::string) but the len parameter specifies the length of sql.
If byteCount is -1 then strlen(sql) is used to find the length.
Definition at line 67 of file sq3.cpp.
References finalize(), sq3::database::handle(), and refcount::rcptr< HandleT, FinalizerT >::take().
int sq3::statement::prepare | ( | std::string const & | sql | ) |
(Re-)prepares an SQL statement.
Return code is that of sqlite3_prepare(). If any value other than SQLITE_OK is returned then preparation failed and this object is not ready to be used.
Definition at line 62 of file sq3.cpp.
Referenced by statement().