RAII encapsulation of a prepared SQLite Statement. More...

#include <Statement.h>

Classes
class	Ptr
	Shared pointer to the sqlite3_stmt SQLite Statement Object. More...

Public Member Functions
	Statement (Database &aDatabase, const char *apQuery)
	Compile and register the SQL query for the provided SQLite Database Connection. More...

virtual	~Statement (void) throw ()
	Finalize and unregister the SQL query from the SQLite Database Connection. More...

void	reset (void)
	Reset the statement to make it ready for a new execution. More...

void	bind (const int aIndex, const int &aValue)
	Bind an int value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const int aIndex, const sqlite3_int64 &aValue)
	Bind a 64bits int value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const int aIndex, const double &aValue)
	Bind a double (64bits float) value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const int aIndex, const std::string &aValue)
	Bind a string value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const int aIndex, const char *apValue)
	Bind a text value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const int aIndex, const void *apValue, const int aSize)
	Bind a binary blob value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const int aIndex)
	Bind a NULL value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const char *apName, const int &aValue)
	Bind an int value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const char *apName, const sqlite3_int64 &aValue)
	Bind a 64bits int value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const char *apName, const double &aValue)
	Bind a double (64bits float) value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const char *apName, const std::string &aValue)
	Bind a string value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const char apName, const char apValue)
	Bind a text value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const char apName, const void apValue, const int aSize)
	Bind a binary blob value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

void	bind (const char *apName)
	Bind a NULL value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1) More...

bool	executeStep (void)
	Execute a step of the prepared query to fetch one row of results. More...

int	exec (void)
	Execute a one-step query with no expected result. More...

Column	getColumn (const int aIndex)
	Return a copie of the column data specified by its index. More...

bool	isColumnNull (const int aIndex) const
	Test if the column value is NULL. More...

const std::string &	getQuery (void) const
	Return the UTF-8 SQL Query. More...

int	getColumnCount (void) const
	Return the number of columns in the result set returned by the prepared statement. More...

bool	isOk (void) const
	true when a row has been fetched with executeStep() More...

bool	isDone (void) const
	true when the last executeStep() had no more row to fetch More...

const char *	errmsg (void) const
	Return UTF-8 encoded English language explanation of the most recent error. More...

Detailed Description

RAII encapsulation of a prepared SQLite Statement.

A Statement is a compiled SQL query ready to be executed step by step to provide results one row at a time.

Resource Acquisition Is Initialization (RAII) means that the Statement is compiled in the constructor and finalized in the destructor, so that there is no need to worry about memory management or the validity of the underlying SQLite Statement.

Definition at line 32 of file Statement.h.

Constructor & Destructor Documentation

SQLite::Statement::Statement	(	Database &	aDatabase,
		const char *	apQuery
	)

Compile and register the SQL query for the provided SQLite Database Connection.

Parameters

[in]	aDatabase	the SQLite Database Connection
[in]	apQuery	an UTF-8 encoded query string

Exception is thrown in case of error, then the Statement object is NOT constructed.

Definition at line 19 of file Statement.cpp.

SQLite::Statement::~Statement ( void ) throw ()

virtual

Finalize and unregister the SQL query from the SQLite Database Connection.

Definition at line 30 of file Statement.cpp.

Member Function Documentation

void SQLite::Statement::bind	(	const int	aIndex,
		const int &	aValue
	)

Bind an int value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 45 of file Statement.cpp.

Here is the caller graph for this function:

void SQLite::Statement::bind	(	const int	aIndex,
		const sqlite3_int64 &	aValue
	)

Bind a 64bits int value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 52 of file Statement.cpp.

void SQLite::Statement::bind	(	const int	aIndex,
		const double &	aValue
	)

Bind a double (64bits float) value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 59 of file Statement.cpp.

void SQLite::Statement::bind	(	const int	aIndex,
		const std::string &	aValue
	)

Bind a string value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Note: This uses the SQLITE_TRANSIENT flag, making a copy of the data, for SQLite internal use

Definition at line 66 of file Statement.cpp.

void SQLite::Statement::bind	(	const int	aIndex,
		const char *	apValue
	)

Bind a text value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Note: This uses the SQLITE_TRANSIENT flag, making a copy of the data, for SQLite internal use

Definition at line 73 of file Statement.cpp.

void SQLite::Statement::bind	(	const int	aIndex,
		const void *	apValue,
		const int	aSize
	)

Bind a binary blob value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Note: This uses the SQLITE_TRANSIENT flag, making a copy of the data, for SQLite internal use

Definition at line 80 of file Statement.cpp.

void SQLite::Statement::bind ( const int aIndex )

Bind a NULL value to a parameter "?", "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 87 of file Statement.cpp.

void SQLite::Statement::bind	(	const char *	apName,
		const int &	aValue
	)

Bind an int value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 95 of file Statement.cpp.

void SQLite::Statement::bind	(	const char *	apName,
		const sqlite3_int64 &	aValue
	)

Bind a 64bits int value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 103 of file Statement.cpp.

void SQLite::Statement::bind	(	const char *	apName,
		const double &	aValue
	)

Bind a double (64bits float) value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 111 of file Statement.cpp.

void SQLite::Statement::bind	(	const char *	apName,
		const std::string &	aValue
	)

Bind a string value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Note: This uses the SQLITE_TRANSIENT flag, making a copy of the data, for SQLite internal use

Definition at line 119 of file Statement.cpp.

void SQLite::Statement::bind	(	const char *	apName,
		const char *	apValue
	)

Bind a text value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Note: This uses the SQLITE_TRANSIENT flag, making a copy of the data, for SQLite internal use

Definition at line 127 of file Statement.cpp.

void SQLite::Statement::bind	(	const char *	apName,
		const void *	apValue,
		const int	aSize
	)

Bind a binary blob value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Note: This uses the SQLITE_TRANSIENT flag, making a copy of the data, for SQLite internal use

Definition at line 135 of file Statement.cpp.

void SQLite::Statement::bind ( const char * apName )

Bind a NULL value to a named parameter "?NNN", ":VVV", "@VVV" or "$VVV" in the SQL prepared statement (aIndex >= 1)

Definition at line 143 of file Statement.cpp.

const char* SQLite::Statement::errmsg ( void ) const

inline

Return UTF-8 encoded English language explanation of the most recent error.

Definition at line 245 of file Statement.h.

int SQLite::Statement::exec ( void )

Execute a one-step query with no expected result.

This method is useful for any kind of statements other than the Data Query Language (DQL) "SELECT" :

Data Definition Language (DDL) statements "CREATE", "ALTER" and "DROP"
Data Manipulation Language (DML) statements "INSERT", "UPDATE" and "DELETE"
Data Control Language (DCL) statements "GRANT", "REVOKE", "COMMIT" and "ROLLBACK"

It is similar to Database::exec(), but using a precompiled statement, it adds :

the ability to bind() arguments to it (best way to insert data),
reusing it allows for better performances (efficent for multiple insersion).

See Also: executeStep() execute a step of the prepared query to fetch one row of results; Database::exec() is a shortcut to execute one or multiple statements without results

Returns: number of row modified by this SQL statement (INSERT, UPDATE or DELETE)

Exceptions

SQLite::Exception in case of error, or if row of results are returned !

Definition at line 182 of file Statement.cpp.

bool SQLite::Statement::executeStep ( void )

Execute a step of the prepared query to fetch one row of results.

While true is returned, a row of results is available, and can be accessed thru the getColumn() method

See Also: exec() execute a one-step prepared statement with no expected result; Database::exec() is a shortcut to execute one or multiple statements without results

Returns

- true (SQLITE_ROW) if there is another row ready : you can call getColumn(N) to get it then you have to call executeStep() again to fetch more rows until the query is finished

false (SQLITE_DONE) if the query has finished executing : there is no (more) row of result (case of a query with no result, or after N rows fetched successfully)

Exceptions

SQLite::Exception in case of error

Definition at line 152 of file Statement.cpp.

Here is the caller graph for this function:

Column SQLite::Statement::getColumn ( const int aIndex )

Return a copie of the column data specified by its index.

Can be used to access the data of the current row of result when applicable, while the executeStep() method returns true.

Throw an exception if there is no row to return a Column from :

before any executeStep() call
after the last executeStep() returned false
after a reset() call

Throw an exception if the specified index is out of the [0, getColumnCount()) range.

Parameters

[in] aIndex Index of the column, starting at 0

Note: This method is no more const, starting in v0.5, which reflects the fact that the returned Column object will share the ownership of the underlying sqlite3_stmt.

Warning: The resulting Column object must not be memorized "as-is". Is is only a wrapper arround the current result row, so it is only valid while the row from the Statement remains valid, that is only until next executeStep() call. Thus, you should instead extract immediately its data (getInt(), getText()...) and use or copy this data for any later usage.

Definition at line 216 of file Statement.cpp.

Here is the caller graph for this function:

int SQLite::Statement::getColumnCount ( void ) const

inline

Return the number of columns in the result set returned by the prepared statement.

Definition at line 230 of file Statement.h.

const std::string& SQLite::Statement::getQuery ( void ) const

inline

Return the UTF-8 SQL Query.

Definition at line 225 of file Statement.h.

bool SQLite::Statement::isColumnNull ( const int aIndex ) const

Test if the column value is NULL.

Parameters

[in] aIndex Index of the column, starting at 0

Returns: true if the column value is NULL

Definition at line 232 of file Statement.cpp.

bool SQLite::Statement::isDone ( void ) const

inline

true when the last executeStep() had no more row to fetch

Definition at line 240 of file Statement.h.

bool SQLite::Statement::isOk ( void ) const

inline

true when a row has been fetched with executeStep()

Definition at line 235 of file Statement.h.

void SQLite::Statement::reset ( void )

Reset the statement to make it ready for a new execution.

Definition at line 36 of file Statement.cpp.

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

src/Statement.h
src/Statement.cpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation