libsq3  2007.10.18
Public Member Functions | Friends | List of all members
sq3::statement Class Reference

#include <sq3.hpp>

Public Member Functions

 statement (database &db)
 Initializes a prepared statement without a query. More...
 
 statement (database &db, std::string const &sql)
 Initializes a statement with the given sql. More...
 
 statement (database &db, char const *sql, int byteCount=-1)
 Initializes a statement with the given sql. More...
 
 ~statement ()
 Calls this->finalize()
 
int prepare (std::string const &sql)
 (Re-)prepares an SQL statement. More...
 
int prepare (char const *sql, int byteCount=-1)
 Same as prepare(std::string) but the len parameter specifies the length of sql. More...
 
int bind (int index)
 Binds NULL to the given placeholder index (1-based, not 0-based!). More...
 
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!). More...
 
int bind (int index, void const *data, int len)
 Binds data to the given placeholder index (1-based, not 0-based!). More...
 
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. More...
 
int bind (char const *index, int data)
 Binds data to the given placeholder index. More...
 
int bind (char const *index, int64_t data)
 Binds data to the given placeholder index. More...
 
int bind (char const *index, double data)
 Binds data to the given placeholder index. More...
 
int bind (char const *index, char const *data, int len)
 Binds data to the given placeholder index. More...
 
int bind (char const *index, void const *data, int len)
 Binds data to the given placeholder index. More...
 
int bind (char const *index, std::string const &data)
 Binds data to the given placeholder index. More...
 
cursor get_cursor ()
 Returns a cursor object ready to step over the result set from this object. More...
 
int execute ()
 Assumes this object's SQL statement is a single statement. More...
 
int execute (int &tgt)
 Executes this statement and saves the return value of that statement in tgt. More...
 
int execute (int64_t &tgt)
 See execute(int&). More...
 
int execute (double &tgt)
 See execute(int&). More...
 
int execute (std::string &tgt)
 See execute(int&). More...
 
int execute (sqlite3_text_char_t const **tgt, int &len)
 See execute(int&). More...
 
int execute (void const **tgt, int &len)
 See execute(sqlite3_text_char_t const ,int&). More...
 
int finalize ()
 Finizalizes the underlying prepared statement, freeing its resources. More...
 
bool is_prepared () const
 Use after construction to ensure that a statement was compiled. More...
 
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. More...
 
char const * colname (int index)
 On success, it returns the null-terminated column name of the given column. More...
 
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. More...
 

Friends

class cursor
 

Detailed Description

   This class represents a prepared database statement.

   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.

Constructor & Destructor Documentation

◆ statement() [1/3]

sq3::statement::statement ( database db)

Initializes a prepared statement without a query.

Use prepare() to prepare the statement.

Definition at line 135 of file sq3.cpp.

◆ statement() [2/3]

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().

◆ statement() [3/3]

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().

Member Function Documentation

◆ bind() [1/10]

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.

Referenced by bind(), sq3::database::clear(), sq3::settings_db::get(), sq3::log_db::log(), and sq3::settings_db::set().

◆ bind() [2/10]

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.

◆ bind() [3/10]

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.

◆ bind() [4/10]

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.

◆ bind() [5/10]

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.

◆ bind() [6/10]

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.

◆ bind() [7/10]

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.

◆ bind() [8/10]

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.

◆ bind() [9/10]

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.

◆ bind() [10/10]

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().

◆ colcount()

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.

Referenced by colname().

◆ colname() [1/2]

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().

Referenced by colname().

◆ colname() [2/2]

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().

◆ execute() [1/7]

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::database::execute(), sq3::settings_db::get(), sq3::log_db::log(), and sq3::settings_db::set().

◆ execute() [2/7]

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.

Definition at line 264 of file sq3.cpp.

◆ execute() [3/7]

int sq3::statement::execute ( int64_t tgt)

See execute(int&).

Definition at line 268 of file sq3.cpp.

◆ execute() [4/7]

int sq3::statement::execute ( double &  tgt)

See execute(int&).

Definition at line 272 of file sq3.cpp.

◆ execute() [5/7]

int sq3::statement::execute ( std::string &  tgt)

See execute(int&).

Definition at line 276 of file sq3.cpp.

◆ execute() [6/7]

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().

◆ execute() [7/7]

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().

◆ finalize()

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.

Referenced by prepare(), and ~statement().

◆ get_cursor()

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().

◆ is_prepared()

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.

◆ prepare() [1/2]

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().

◆ prepare() [2/2]

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(), and sq3::database::handle().


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