/sqlite3cc

/*

 * basic_statement.h

 *

 * Copyright (C) 2009 Tim Marston <edam@waxworlds.org>

 *

 * This file is part of sqlite3cc (hereafter referred to as "this program").

 * See http://www.waxworlds.org/edam/software/sqlite3cc for more information.

 *

 * This program is free software: you can redistribute it and/or modify

 * it under the terms of the GNU Lesser General Public License as published

 * by the Free Software Foundation, either version 3 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public License

 * along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

#ifndef SQLITE3CC_BASIC_STATEMENT_H_

#define SQLITE3CC_BASIC_STATEMENT_H_

#include <sqlite3.h>

#include <boost/utility.hpp>

#include <boost/lexical_cast.hpp>

#include <sqlite3cc/exception.h>

namespace sqlite

{

class database;

class row;

struct _null_t;

struct _exec_t;

struct _set_index_t;

/**

 * The statement class represents an SQL statement. It is the base class for

 * both the command and the query classes, which should be used for those

 * purposes. The basic_statement class its self has protected instantiation.

 */

class basic_statement

	:

	private boost::noncopyable

{

//______________________________________________________________________________

//                                                                 instantiation

protected:

	/**

	 * Constructor that provides a database upon which to act and the SQL

	 * statement.

	 * @param database a reference to a database

	 * @param sql an SQL statement in UTF-8

	 */

	explicit basic_statement(

		database &database,

		const std::string &sql );

	/**

	 * Constructor that provides a database upon which to act.

	 * @param database a reference to a database

	 * @param sql an SQL statement in UTF-8

	 */

	explicit basic_statement(

		database &database );

	virtual ~basic_statement() throw( );

//______________________________________________________________________________

//                                                              public interface

public:

	/**

	 * Prepare an SQL statement.

	 * @param sql an SQL statement in UTF-8

	 * @returns an sqlite error code

	 * @see sqlite3_prepare_v2()

	 */

	virtual int prepare(

		const std::string &sql );

	/**

	 * Reset the statement, ready to re-execute it. This does not clear any of

	 * the values bound to the statement.

	 * @returns an sqlite error code

	 * @see sqlite3_reset()

	 */

	int reset();

	/**

	 * Clears the values bound to a statement to NULL.

	 * @returns an sqlite error code

	 * @see sqlite3_clear_bindings()

	 */

	int clear_bindings();

	/**

	 * Bind a value to the SQL statement via it's index. This template will take

	 * a variety of data types and bind them as text. This is how sqlite

	 * internally stores the data anyway, so always binding as text just means

	 * we do the conversion instead of sqlite and is no less efficient.

	 * @param index the index of the parameter to bind to

	 * @param value the value to bind

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	template< class T >

	int bind(

		unsigned int index,

		T value )

	{

		std::string string_value = boost::lexical_cast< std::string >( value );

		return sqlite3_bind_text( _handle, index, string_value.c_str(),

			string_value.length(), SQLITE_TRANSIENT );

	}

	/**

	 * Bind a string value to the SQL statement via it's index where the value

	 * of that string will not change for the duration of the statement. This is

	 * more optimal because sqlite will not have to make it's own copy of the

	 * data.

	 * @param index the index of the parameter to bind to

	 * @param value the invariant string value

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	int bind_static(

		unsigned int index,

		const char *value,

		unsigned int value_length );

	/**

	 * Bind a string value to the SQL statement via it's index where the value

	 * of that string will not change for the duration of the statement. This is

	 * more optimal  because sqlite will not have to make it's own copy of the

	 * data.

	 * @param index the index of the parameter to bind to

	 * @param value the invariant string value

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	int bind_static(

		unsigned int index,

		const char *value );

	/**

	 * Bind a string value to the SQL statement via it's index where the value

	 * of that string will not change for the duration of the statement. This is

	 * more optimal because sqlite will not have to make it's own copy of the

	 * data.

	 * @param index the index of the parameter to bind to

	 * @param value the invariant string value

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	int bind_static(

		unsigned int index,

		const std::string &value );

	/**

	 * Bind a NULL value to the SQL statement via it's index.

	 * @param index the index of the parameter to bind to

	 * @returns an sqlite error code

	 * @see sqlite3_bind_null()

	 */

	int bind_null(

		unsigned int index );

	/**

	 * Bind a value to the SQL statement via a named parameter. This template

	 * will take a variety of data types and bind them as text. This is how

	 * sqlite internally stores the data anyway, so always binding as text just

	 * means we do the conversion instead of sqlite and is no less efficient.

	 * @param name the named parameter to bind to

	 * @param value the value to bind

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	template< class T >

	int bind(

		const std::string &name,

		T value )

	{

		return bind( bind_parameter_index( name ), value );

	}

	/**

	 * Bind a string value to the SQL statement via a named parameter where the

	 * string value will not change for the duration of the statement. This

	 * prevents a copy of the string being taken.

	 * @param name the named parameter to bind to

	 * @param value the invariant string value

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	int bind_static(

		const std::string &name,

		const char *value,

		unsigned int value_length );

	/**

	 * Bind a string value to the SQL statement via a named parameter where the

	 * string value will not change for the duration of the statement. This

	 * prevents a copy of the string being taken.

	 * @param name the named parameter to bind to

	 * @param value the invariant string value

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	int bind_static(

		const std::string &name,

		const char *value );

	/**

	 * Bind a string value to the SQL statement via a named parameter where the

	 * string value will not change for the duration of the statement. This

	 * prevents a copy of the string being taken.

	 * @param name the named parameter to bind to

	 * @param value the invariant string value

	 * @returns an sqlite error code

	 * @see sqlite3_bind_text()

	 */

	int bind_static(

		const std::string &name,

		const std::string &value );

	/**

	 * Bind a NULL value to the SQL statement via a named parameter.

	 * @param name the named parameter to bind to

	 * @returns an sqlite error code

	 * @see sqlite3_bind_null()

	 */

	int bind_null(

		const std::string &name );

	/**

	 * Stream operator is used to bind values to parameters automatically, in

	 * ascending order. In addition, the null, set_index() and execute auto-

	 * binding manipulators can be used.

	 * @param value a value to bind

	 */

	template< class T >

	basic_statement &operator <<(

		const T &value )

	{

		int error_code = bind( _bind_index, value );

		if( error_code != SQLITE_OK ) throw sqlite_error( error_code );

		_bind_index++;

		return *this;

	}

//______________________________________________________________________________

//                                                                implementation

protected:

	friend class row;

	/**

	 * Finalise an SQL statement.

	 * @returns an sqlite error code

	 * @see sqlite3_finalize()

	 */

	int finalize();

	/**

	 * Step through one execution cycle of the SQL statement. If this is an SQL

	 * statement that doesn't return any rows, only one cycle is required,

	 * otherwise, each cycle will return another row

	 * @return an sqlite error code

	 * @see sqlite3_step()

	 */

	int step();

	/**

	 * Get the index number of a named parameter

	 * @param parameter name

	 * @return index of named parameter

	 */

	int bind_parameter_index(

		const std::string &name );

	/** the database upon which to act */

	database &_database;

	/** the statement handle */

	sqlite3_stmt *_handle;

private:

	/** index used when auto-binding */

	unsigned int _bind_index;

};

// template specialisations for statement::operator <<()

template< >

basic_statement &basic_statement::operator << < _null_t >(

	const _null_t & );

template< >

basic_statement &basic_statement::operator << < _exec_t >(

	const _exec_t & );

template< >

basic_statement &basic_statement::operator << < _set_index_t >(

	const _set_index_t &t );

} // namespace sqlite

#endif /* SQLITE3CC_BASIC_STATEMENT_H_ */