/sqlite3cc

/*

 * statement.hpp

 *

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

 *

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

 * See http://www.waxworlds.org/edam/software/sqlitepp 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 STATEMENT_HPP_

#define STATEMENT_HPP_

#include <sqlite3.h>

#include <boost/utility.hpp>

#include <boost/lexical_cast.hpp>

#include <sqlitepp/exception.hpp>

namespace sqlite

{

class database;

struct _null_t { };

struct _exec_t { };

struct _set_index_t { unsigned int _index; };

/**

 * Auto-binding manipulator, for use with a statment's stream operator. This

 * specifies a NULL value to bind to a parameter.

 */

extern const _null_t null;

/**

 * Auto-binding manipulator, for use with a statment's stream operator. This

 * indicates that the statement should be executed immediately. Unlike a

 * statment's exec() method, this will throw on error. Also, it will throw if

 * the execution returns any result rows.

 */

extern const _exec_t exec;

/**

 * Auto-binding manipulator, for use with a statment's stream operator. This

 * manipulator sets the index used to automatically assign values to parameters.

 * @param index the new index for incremental assignment

 */

_set_index_t set_index(

	unsigned int index );

/**

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

 * the command and the query classes which should be used for those purposes.

 * The statement class its self has protected instantiation.

 */

class statement

	:

	private boost::noncopyable

{

//______________________________________________________________________________

//                                                                 instantiation

protected:

	/**

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

	 * statement.

	 * @param database a reference to the database

	 * @param sql an SQL statement in UTF-8

	 */

	statement(

		database &database,

		const std::string &sql );

	virtual ~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()

	 */

	int prepare(

		const std::string &sql );

	/**

	 * 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();

	/**

	 * 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 )

	{

		unsigned int index =

			sqlite3_bind_parameter_index( _handle, name.c_str() );

		return bind( index, 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, execute and set_index() auto-

	 * binding manipulators can be used.

	 * @param value a value to bind

	 */

	template< class T >

	statement &operator <<( 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:

	/**

	 * Finalise an SQL statement.

	 * @returns an sqlite error code

	 * @see sqlite3_finalize()

	 */

	int finalize();

private:

	/** the database upon which to act */

	database &_database;

	/** the statement handle */

	sqlite3_stmt *_handle;

	/** index used when auto-binding */

	unsigned int _bind_index;

};

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

template< >

statement& statement::operator << < _null_t >(

	_null_t );

template< >

statement& statement::operator << < _exec_t >(

	_exec_t );

template< >

statement& statement::operator << < _set_index_t >(

	_set_index_t t );

}

#endif /* STATEMENT_HPP_ */