#include <sq3.hpp>
Public Member Functions | |
cursor () | |
Creates an empty cursor, whose only valid use is to assign it from another cursor. | |
cursor (cursor const &rhs) | |
Copies rhs. | |
cursor & | operator= (cursor const &) |
See the copy ctor. | |
cursor (statement &st) | |
Identical to calling st.get_cursor(). | |
~cursor () | |
A curious side-effect which one needs to be aware of but very rarely is an issue:. | |
int | step () |
Uses sqlite3_step() to step through this object's data set by one step. | |
int | reset () |
This is functionally the same as calling reset on the underlying prepared statement object to which this cursor is tied. | |
void | close () |
"Disconnects" this object from the underlying result set, making this object useless for anything but as the target of an assignment. | |
int | colcount () |
Returns the column count of the underlying prepared statement. | |
int | isnull (int index, bool &tgt) |
If column index (0-based) is in bounds then this function check if the value of the given column index is NULL and assigns tgt to the result of this comprobation. | |
int | get (int index, int &tgt) |
If column index (0-based) is in bounds then this function assigns tgt to the value of the given column index. | |
int | get (int index, int64_t &tgt) |
See get(int,int&). | |
int | get (int index, double &tgt) |
See get(int,int&). | |
int | get (int index, std::string &tgt) |
See get(int,int&). | |
int | get (int index, sqlite3_text_char_t const **tgt, int &sz) |
If index (0-based) is in bounds, this function gets the (char unsigned const *) data at that column index and assigns tgt to that value and sz to the size of the data. | |
int | get (int index, void const **tgt, int &sz) |
See get(int,char const **, int&). | |
int | get (std::string const &key, int &tgt) |
This is fundamentally identical to get(int,int &) except that the key type is a string, which must exactly (case-sensitively) match a column name from this result set. | |
int | get (std::string const &key, int64_t &tgt) |
See get(std::string const &,int&). | |
int | get (std::string const &key, double &tgt) |
See get(std::string const &,int&). | |
int | get (std::string const &key, std::string &tgt) |
See get(std::string const &,int&). | |
int | get (std::string const &key, sqlite3_text_char_t const **tgt, int &sz) |
If indexis in bounds, this function gets the (char unsigned const *) data at that column index and assigns tgt to that value and sz to the size of the data. | |
int | get (std::string const &key, void const **tgt, int &sz) |
See get(std::string const &,char const **, int&). | |
int | colname (int index, std::string &str) |
Sets str to the column name as the given index (0-based). | |
int | colname (int index, char const **str) |
Points str to the nul-terminated column name at the given index (0-based), or 0 on error. |
Clients do not normally create cursors directly, but through the statement::get_cursor() function.
cursor objects are copied shallowly - each copy points back to a single original statement object. That statement is reset when the last of these copies goes out of scope or is finalized.
Definition at line 684 of file sq3.hpp.
sq3::cursor::cursor | ( | cursor const & | rhs | ) |
sq3::cursor::~cursor | ( | ) |
A curious side-effect which one needs to be aware of but very rarely is an issue:.
When cursors are created they *always* have an associated prepared statement. When the last cursor with a reference to that same statement goes out of scope or is close()ed then the underlying statement object is reset(). That sounds curious, but is indeed the desired behaviour for this class, and breaks some common client code constructs when the underlying statement is not automatically reset. Without this "feature", client code could not run, for exaple, myStatement.execute( myInt ), two times in a row because the second time around the statement would be at its end point and need to be manually reset. Thus client code should never mix the use of a cursor object and the non-cursor statement API on the same statement.
See statement::close() for more details.
Definition at line 365 of file sq3.cpp.
References close().
void sq3::cursor::close | ( | ) |
"Disconnects" this object from the underlying result set, making this object useless for anything but as the target of an assignment.
It is normally not necessary to call this function, but it may be in some special cases.
Definition at line 385 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::take().
Referenced by ~cursor().
int sq3::cursor::colcount | ( | ) |
Returns the column count of the underlying prepared statement.
May return 0 for queries which has no return value (e.g. UPDATE). Returns -1 on error.
Definition at line 395 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::cursor::colname | ( | int | index, | |
char const ** | str | |||
) |
Points str to the nul-terminated column name at the given index (0-based), or 0 on error.
This overload avoids an extra copy of the column name, but sqlite owns the string and clients will need to make a copy of it if they want to continue to use it beyond the lifetime of this object's underlying prepared statement.
Returns SQLITE_OK if str is set, otherwise SQLITE_ERROR.
int sq3::cursor::colname | ( | int | index, | |
std::string & | str | |||
) |
int sq3::cursor::get | ( | std::string const & | key, | |
void const ** | tgt, | |||
int & | sz | |||
) |
int sq3::cursor::get | ( | std::string const & | key, | |
sqlite3_text_char_t const ** | tgt, | |||
int & | sz | |||
) |
If indexis in bounds, this function gets the (char unsigned const *) data at that column index and assigns tgt to that value and sz to the size of the data.
tgt is written to by this func but ownership of the underlying data remains with sqlite. That is, the caller does not need to free the memory pointed to by tgt, but may need to copy it if he wants to use it later.
int sq3::cursor::get | ( | std::string const & | key, | |
int & | tgt | |||
) |
This is fundamentally identical to get(int,int &) except that the key type is a string, which must exactly (case-sensitively) match a column name from this result set.
On success, SQLITE_OK is returned and tgt is modified. On error, some other code is returned and tgt is not modified.
Note that fetching by string index is much less efficient than looking up by integer index, but of course also a lot more convenient. If you're looking for the most speed, go with get(int,...). If you're looking for flexibility and convenience, at the cost of a few extra cyles and a tiny bit of extra memory usage per cursor, then use string-based keys.
int sq3::cursor::get | ( | int | index, | |
void const ** | tgt, | |||
int & | sz | |||
) |
See get(int,char const **, int&).
Only the tgt type is different.
Definition at line 460 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::cursor::get | ( | int | index, | |
sqlite3_text_char_t const ** | tgt, | |||
int & | sz | |||
) |
If index (0-based) is in bounds, this function gets the (char unsigned const *) data at that column index and assigns tgt to that value and sz to the size of the data.
tgt is written to by this func but ownership of the underlying data remains with sqlite. That is, the caller does not need to free the memory pointed to by tgt, but may need to copy it if he wants to use it later.
Definition at line 446 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::cursor::get | ( | int | index, | |
int & | tgt | |||
) |
If column index (0-based) is in bounds then this function assigns tgt to the value of the given column index.
On success, SQLITE_OK is returned. On any other return value, tgt is not modifed.
Definition at line 413 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
Referenced by sq3::statement::execute(), and sq3::log_db::show_last().
int sq3::cursor::isnull | ( | int | index, | |
bool & | tgt | |||
) |
If column index (0-based) is in bounds then this function check if the value of the given column index is NULL and assigns tgt to the result of this comprobation.
On success, SQLITE_OK is returned. On any other return value, tgt is not modifed.
Definition at line 406 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::cursor::reset | ( | ) |
This is functionally the same as calling reset on the underlying prepared statement object to which this cursor is tied.
Use with care, as it affects all cursors which point to the same statement object.
returns SQLITE_OK on success, else another sqlite3 error code.
Definition at line 377 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
int sq3::cursor::step | ( | ) |
Uses sqlite3_step() to step through this object's data set by one step.
Returns the result of sqlite3_step(), which means: SQLITE_ROW if it read, SQLITE_DONE at the end of a data set, and any other value on error.
Definition at line 370 of file sq3.cpp.
References refcount::rcptr< HandleT, FinalizerT >::get().
Referenced by sq3::statement::execute(), and sq3::log_db::show_last().