libfossil
fsl::Stmt Class Reference

A prepared statement, the C++ counterpart to fsl_stmt. More...

#include "fossil.hpp"

Public Member Functions

 Stmt (Db &db) throw ()
 Sets up initial state. More...
 
 ~Stmt () throw ()
 Frees any underlying resources. More...
 
Stmtbind (short colOneBased)
 Analog to fsl_stmt_bind_null() More...
 
Stmtbind (short colOneBased, fsl_int32_t v)
 Analog to fsl_stmt_bind_int32() More...
 
Stmtbind (short colOneBased, fsl_int64_t v)
 Analog to fsl_stmt_bind_int64() More...
 
Stmtbind (short colOneBased, double v)
 Analog to fsl_stmt_bind_int64() More...
 
Stmtbind (short colOneBased, char const *str, fsl_int_t len=-1, bool copyBytes=true)
 Analog to fsl_stmt_bind_text() More...
 
Stmtbind (short colOneBased, std::string const &str)
 Equivalent to bind(colOneBased, str.c_str(), str.size());. More...
 
Stmtbind (short colOneBased, void const *blob, fsl_size_t len, bool copyBytes=true)
 Analog to fsl_stmt_bind_blob() More...
 
Stmtbind (char const *col)
 Analog to fsl_stmt_bind_null_name() More...
 
Stmtbind (char const *col, fsl_int32_t v)
 Analog to fsl_stmt_bind_int32_name() More...
 
Stmtbind (char const *col, fsl_int64_t v)
 Analog to fsl_stmt_bind_int64_name() More...
 
Stmtbind (char const *col, double v)
 Analog to fsl_stmt_bind_double_name() More...
 
Stmtbind (char const *col, char const *str, fsl_int_t len=-1, bool copyBytes=true)
 Analog to fsl_stmt_bind_text_name() More...
 
Stmtbind (char const *col, std::string const &str)
 Equivalent to bind(col, str.c_str(), str.size());. More...
 
Stmtbind (char const *col, void const *blob, fsl_size_t len, bool copyBytes=true)
 Analog to fsl_stmt_bind_blob_name() More...
 
template<typename IteratorT >
StmtbindIter (IteratorT const &begin, IteratorT const &end)
 Binds each entry of the input iterator range [begin,end), starting at index 1 and moving up. More...
 
template<typename ListType >
StmtbindList (ListType const &li)
 Binds each entry of the given std::list-like type. More...
 
int columnCount () const throw ()
 Returns the number of "fetchable" columns in the statement. More...
 
char const * columnName (short colZeroBased)
 Analog to fsl_stmt_col_name() More...
 
template<typename Func >
StmteachRow (Func const &func)
 Runs a loop over func(*this), calling it once for each time this->step() returns true. More...
 
template<typename State , typename Func >
StmteachRow (Func const &func, State &state)
 Runs a loop over func(*this, state), calling it once for each time this->step() returns true. More...
 
template<typename State >
StmteachRow (fsl_stmt_each_f func, State &state)
 Runs a loop over func(this->handle(), &state), calling it once for each time this->step() returns true. More...
 
Stmtfinalize () throw ()
 Frees any underlying resources owned by this statement. More...
 
void const * getBlob (short colZeroBased, fsl_size_t *length=NULL)
 Analog to fsl_stmt_g_blob() More...
 
double getDouble (short colZeroBased)
 Analog to fsl_stmt_g_double() More...
 
fsl_id_t getId (short colZeroBased)
 Analog to fsl_stmt_g_id() More...
 
fsl_int32_t getInt32 (short colZeroBased)
 Analog to fsl_stmt_g_int64() More...
 
fsl_int64_t getInt64 (short colZeroBased)
 Analog to fsl_stmt_g_int64() More...
 
char const * getText (short colZeroBased, fsl_size_t *length=NULL)
 Analog to fsl_stmt_g_text() More...
 
fsl_stmthandle () throw ()
 Returns this object's C-level fsl_stmt handle. More...
 
fsl_stmt const * handle () const throw ()
 Const-correct overload. More...
 
 operator fsl_stmt * () throw ()
 Implicit conversion to (fsl_stmt *) to simplify usage with the C API. More...
 
 operator fsl_stmt const * () const throw ()
 Const-correct overload. More...
 
int paramCount () const throw ()
 Returns the number of bound parameters in the statement. More...
 
int paramIndex (char const *name)
 Analog to fsl_stmt_param_index() More...
 
Stmtprepare (char const *sql,...)
 Basically a proxy for fsl_db_prepare(), this routine sets this object's statement up from the given formatted SQL string. More...
 
Stmtprepare (std::string const &sql)
 Equivalent to this->prepare(db, "%s", sql.c_str()). More...
 
Stmtprepare (Buffer const &sql)
 Equivalent to this->prepare(db, "%s", sql.c_str()). More...
 
Stmtreset (bool resetStepCounterToo=false)
 "Resets" the statement so it can be executed again, as per fsl_stmt_reset(). More...
 
char const * sql () const throw ()
 Returns the SQL of the statement, or NULL if the statement is not prepared. More...
 
bool step ()
 Steps one row. More...
 
int stepCount () const throw ()
 Returns the number of times step() has fetched a row of data since this counter was last reset. More...
 
StmtstepExpectDone ()
 step()s the statement one time and throws if the step() call does _not_ return false. More...
 

Friends

class Db
 

Detailed Description

A prepared statement, the C++ counterpart to fsl_stmt.

The vast majority of the members (those not marked with throw()) throw an Exception on error.

Sample usage:

Stmt st(myDb);
st.prepare("SELECT blah FROM foo WHERE id=?")
.bind(1,42)
.eachRow( MyStepFunctor() )
.finalize();

While they are normally created on the stack, they may live on the heap as long as they do not outlive their database.

Definition at line 416 of file fossil.hpp.

Constructor & Destructor Documentation

fsl::Stmt::Stmt ( Db db)
throw (
)
explicit

Sets up initial state.

Most of the member functions will throw until this statement is prepared (via Db::prepare()).

fsl::Stmt::~Stmt ( )
throw (
)

Frees any underlying resources.

Member Function Documentation

Stmt& fsl::Stmt::bind ( short  colOneBased)
Stmt& fsl::Stmt::bind ( short  colOneBased,
fsl_int32_t  v 
)
Stmt& fsl::Stmt::bind ( short  colOneBased,
fsl_int64_t  v 
)
Stmt& fsl::Stmt::bind ( short  colOneBased,
double  v 
)
Stmt& fsl::Stmt::bind ( short  colOneBased,
char const *  str,
fsl_int_t  len = -1,
bool  copyBytes = true 
)
Stmt& fsl::Stmt::bind ( short  colOneBased,
std::string const &  str 
)

Equivalent to bind(colOneBased, str.c_str(), str.size());.

Stmt& fsl::Stmt::bind ( short  colOneBased,
void const *  blob,
fsl_size_t  len,
bool  copyBytes = true 
)
Stmt& fsl::Stmt::bind ( char const *  col)
Stmt& fsl::Stmt::bind ( char const *  col,
fsl_int32_t  v 
)
Stmt& fsl::Stmt::bind ( char const *  col,
fsl_int64_t  v 
)
Stmt& fsl::Stmt::bind ( char const *  col,
double  v 
)
Stmt& fsl::Stmt::bind ( char const *  col,
char const *  str,
fsl_int_t  len = -1,
bool  copyBytes = true 
)
Stmt& fsl::Stmt::bind ( char const *  col,
std::string const &  str 
)

Equivalent to bind(col, str.c_str(), str.size());.

Stmt& fsl::Stmt::bind ( char const *  col,
void const *  blob,
fsl_size_t  len,
bool  copyBytes = true 
)
template<typename IteratorT >
Stmt& fsl::Stmt::bindIter ( IteratorT const &  begin,
IteratorT const &  end 
)
inline

Binds each entry of the input iterator range [begin,end), starting at index 1 and moving up.

Definition at line 643 of file fossil.hpp.

References fsl::Buffer::end().

template<typename ListType >
Stmt& fsl::Stmt::bindList ( ListType const &  li)
inline

Binds each entry of the given std::list-like type.

Each entry in the list is bound starting at index 1 and moving up.

Definition at line 656 of file fossil.hpp.

Referenced by fsl::StmtBinder::bindList().

int fsl::Stmt::columnCount ( ) const
throw (
)

Returns the number of "fetchable" columns in the statement.

char const* fsl::Stmt::columnName ( short  colZeroBased)
template<typename Func >
Stmt& fsl::Stmt::eachRow ( Func const &  func)
inline

Runs a loop over func(*this), calling it once for each time this->step() returns true.

Definition at line 619 of file fossil.hpp.

template<typename State , typename Func >
Stmt& fsl::Stmt::eachRow ( Func const &  func,
State &  state 
)
inline

Runs a loop over func(*this, state), calling it once for each time this->step() returns true.

Definition at line 631 of file fossil.hpp.

template<typename State >
Stmt& fsl::Stmt::eachRow ( fsl_stmt_each_f  func,
State &  state 
)
inline

Runs a loop over func(this->handle(), &state), calling it once for each time this->step() returns true.

If func() returns 0 the loop continues. If it returns FSL_RC_BREAK then the loop stops without an error. If some other value is returned an exception is thrown. Basically a templated form of fsl_stmt_each().

Definition at line 669 of file fossil.hpp.

References FSL_RC_BREAK, and fsl_rc_cstr().

Stmt& fsl::Stmt::finalize ( )
throw (
)

Frees any underlying resources owned by this statement.

It can be prepared() again after calling this.

void const* fsl::Stmt::getBlob ( short  colZeroBased,
fsl_size_t length = NULL 
)

Analog to fsl_stmt_g_blob()

double fsl::Stmt::getDouble ( short  colZeroBased)
fsl_id_t fsl::Stmt::getId ( short  colZeroBased)

Analog to fsl_stmt_g_id()

fsl_int32_t fsl::Stmt::getInt32 ( short  colZeroBased)

Analog to fsl_stmt_g_int64()

fsl_int64_t fsl::Stmt::getInt64 ( short  colZeroBased)

Analog to fsl_stmt_g_int64()

char const* fsl::Stmt::getText ( short  colZeroBased,
fsl_size_t length = NULL 
)

Analog to fsl_stmt_g_text()

fsl_stmt* fsl::Stmt::handle ( )
throw (
)

Returns this object's C-level fsl_stmt handle.

Provided so that client APIs can use fsl_stmt_xxx() functions not wrapped by the C++ APIs. DO NOT, under ANY CIRCUMSTANCES, delete, free, fsl_stmt_finalize(), nor otherwise mess with this handle's ownership. It is owned by this object.

Returns NULL if not yet prepared.

fsl_stmt const* fsl::Stmt::handle ( ) const
throw (
)

Const-correct overload.

fsl::Stmt::operator fsl_stmt * ( )
throw (
)

Implicit conversion to (fsl_stmt *) to simplify usage with the C API.

ABSOLUTELY DO NOT:

  • ... use this conversion to pass this object to fsl_stmt_finalize()!!! Doing so will lead to a dangling pointer and an eventual segfault and/or double-free().
  • ... expect this conversion to be picked up when a function takes a void pointer argument.
fsl::Stmt::operator fsl_stmt const * ( ) const
throw (
)

Const-correct overload.

int fsl::Stmt::paramCount ( ) const
throw (
)

Returns the number of bound parameters in the statement.

int fsl::Stmt::paramIndex ( char const *  name)
Stmt& fsl::Stmt::prepare ( char const *  sql,
  ... 
)

Basically a proxy for fsl_db_prepare(), this routine sets this object's statement up from the given formatted SQL string.

See fsl_appendf() for the supported formatting specifiers.

When passing on strings from external sources, it is safest to pass "%s" as the format string and the foreign string as the first variadic argument. That ensures that percent signs in the foreign input do not get processed as format specifiers (which expect further arguments in the variadic list, which will likely lead to undefined behaviour).

Throws on error. Returns this object.

Stmt& fsl::Stmt::prepare ( std::string const &  sql)

Equivalent to this->prepare(db, "%s", sql.c_str()).

Stmt& fsl::Stmt::prepare ( Buffer const &  sql)

Equivalent to this->prepare(db, "%s", sql.c_str()).

Stmt& fsl::Stmt::reset ( bool  resetStepCounterToo = false)

"Resets" the statement so it can be executed again, as per fsl_stmt_reset().

If resetStepCounterToo is true then the step-counter is also reset to 0 (see fsl_stmt_reset2() and stepCount()).

Returns this object.

char const* fsl::Stmt::sql ( ) const
throw (
)

Returns the SQL of the statement, or NULL if the statement is not prepared.

bool fsl::Stmt::step ( )

Steps one row.

Returns true if it fetches a row, false at the end of the result set (and for non-fetching queries like INSERT/UPDATE/DELETE), and throws on error.

int fsl::Stmt::stepCount ( ) const
throw (
)

Returns the number of times step() has fetched a row of data since this counter was last reset.

Stmt& fsl::Stmt::stepExpectDone ( )

step()s the statement one time and throws if the step() call does _not_ return false.

This is intended for stepping inserts, updates, and other non-fetching queries. Throws on error, returns this object on success.

Friends And Related Function Documentation

friend class Db
friend

Definition at line 688 of file fossil.hpp.


The documentation for this class was generated from the following file: