statement Class Reference

Prepared Statement Object. More...

Inheritance diagram for statement:

Public Types
enum class	explain_type : int { not_explain = 0 , explain = 1 , explain_query_plan = 2 }
	Return type for isexplain() More...

Public Member Functions
	~statement () noexcept
	Equivalent to sqlite3_finalize.
class database &	database () const noexcept
	Returns the database to which this statement belongs.
bool	step ()
	Evaluate the statement.
void	reset () noexcept
	Reset the statement.
bool	busy () const noexcept
	Determine if the statement has been reset.
explain_type	isexplain () const noexcept
	Query the EXPLAIN Setting for the statement.
bool	readonly () const noexcept
	Determine if the statement writes to the database.
int	column_count () const noexcept
	Number of columns in a result set.
int	data_count () const noexcept
	Number of columns in a result set.
const char *	sql () const noexcept
	Returns a pointer to a copy of the SQL text used to create the statement.
allocated_string	expanded_sql () const
	Returns SQL text of the statement with bound parameters expanded.
void	operator delete (void *) noexcept
	Operator delete for a fake pointer is no-op.
sqlite3_stmt *	c_ptr () const noexcept
	Access the real underlying SQLite type.
Binding values to parameters
This set of overloaded functions wraps sqlite3_bind_ function group.
void	bind (int idx, std::nullptr_t)
	Bind a NULL value to a parameter of the statement.
void	bind (int idx, int val)
	Bind an int value to a parameter of the statement.
void	bind (int idx, int64_t val)
	Bind an int64_t value to a parameter of the statement.
void	bind (int idx, double val)
	Bind a double value to a parameter of the statement.
void	bind (int idx, const std::string_view &val)
	Bind a string value to a parameter of the statement.
void	bind_reference (int idx, const std::string_view &val)
	Bind a string reference to a parameter of the statement.
void	bind_reference (int idx, const std::string_view &val, void(*unref)(const char *))
	Bind a string reference to a parameter of the statement.
void	bind (int idx, const std::u8string_view &val)
	Bind a string value to a parameter of the statement.
void	bind_reference (int idx, const std::u8string_view &val)
	Bind a string reference to a parameter of the statement.
void	bind_reference (int idx, const std::u8string_view &val, void(*unref)(const char8_t *))
	Bind a string reference to a parameter of the statement.
void	bind (int idx, const blob_view &val)
	Bind a blob value to a parameter of the statement.
void	bind_reference (int idx, const blob_view &val)
	Bind a blob reference to a parameter of the statement.
void	bind_reference (int idx, const blob_view &val, void(*unref)(const std::byte *))
	Bind a blob reference to a parameter of the statement.
void	bind (int idx, const zero_blob &val)
	Bind a blob of zeroes to a parameter of the statement.
template<class T >
void	bind (int idx, T *ptr, const char *type, void(*destroy)(T *))
template<class T >
void	bind (int idx, std::unique_ptr< T > ptr)
	Bind a custom pointer to a parameter of the statement.
void	bind (int idx, const value &val)
	Bind a dynamically typed value to a parameter of the statement.
Managing parameter bindings
void	clear_bindings () noexcept
	Reset all bindings on the statement.
int	bind_parameter_count () const noexcept
	Returns the number of SQL parameters.
int	bind_parameter_index (const string_param &name) const noexcept
	Returns the index of a parameter with a given name.
const char *	bind_parameter_name (int idx) const noexcept
	Returns the name of a parameter with a given index.
Obtaining query results information by column
template<class T >
T	column_value (int idx) const noexcept
	Get result value from a query.
const value &	raw_column_value (int idx) const noexcept
	Get result values from a query as a raw value object.
int	column_type (int idx) const noexcept
	Default datatype of the result column.
const char *	column_name (int idx) const noexcept
	Name of the result column.
const char *	column_database_name (int idx) const noexcept
	Database that is the origin of a result column.
const char *	column_table_name (int idx) const noexcept
	Table that is the origin of a result column.
const char *	column_origin_name (int idx) const noexcept
	Table column that is the origin of a result column.
const char *	column_declared_type (int idx) const noexcept
	Declared datatype of a result column.

Static Public Member Functions
static std::unique_ptr< statement >	create (const database &db, const string_param &sql, unsigned int flags=0)
	Compile an SQL statement.
static std::unique_ptr< statement >	create (const database &db, std::string_view &sql, unsigned int flags=0)
	Compile an SQL statement.
static std::unique_ptr< statement >	create (const database &db, const u8string_param &sql, unsigned int flags=0)
	Compile an SQL statement.
static std::unique_ptr< statement >	create (const database &db, std::u8string_view &sql, unsigned int flags=0)
	Compile an SQL statement.
static statement *	from (sqlite3_stmt *obj) noexcept
	Create fake pointer from the underlying SQLite one.

Detailed Description

Prepared Statement Object.

This is a fake wrapper class for sqlite3_stmt.

#include <thinsqlitepp/statement.hpp>

Member Enumeration Documentation

explain_type

enum class explain_type : int

strong

Return type for isexplain()

Enumerator
not_explain	0	The statement is an ordinary statement.
explain	1	The statement is an EXPLAIN statement.
explain_query_plan	2	The statement is an EXPLAIN QUERY PLAN.

Member Function Documentation

create() [1/4]

static std::unique_ptr< statement > create ( const database & db, const string_param & sql, unsigned int flags = 0 )

static

Compile an SQL statement.

This is a wrapper over sqlite3_prepare_v3 or sqlite3_prepare_v2, if the former is not available.

Parameters

db	The database to create statement for
sql	The statement to be compiled. Must be in UTF-8.
flags	Zero or more SQLITE_PREPARE_ flags. Only available for SQLite 3.2 or greater

create() [2/4]

static std::unique_ptr< statement > create ( const database & db, std::string_view & sql, unsigned int flags = 0 )

static

Compile an SQL statement.

This is a wrapper over sqlite3_prepare_v3 or sqlite3_prepare_v2, if the former is not available.

Parameters

db	The database to create statement for
sql	The statement to be compiled. Must be in UTF-8. This is an input-output parameter. On output the string_view is adjusted to contain any text past the end of the first SQL statement. See pzTail argument description for sqlite3_prepare_v3
flags	Zero or more SQLITE_PREPARE_ flags. Only available for SQLite 3.2 or greater

create() [3/4]

static std::unique_ptr< statement > create ( const database & db, const u8string_param & sql, unsigned int flags = 0 )

inlinestatic

Compile an SQL statement.

char8_t overload for create(const database &, const string_param &, unsigned int)

create() [4/4]

static std::unique_ptr< statement > create ( const database & db, std::u8string_view & sql, unsigned int flags = 0 )

inlinestatic

Compile an SQL statement.

char8_t overload for create(const database &, std::string_view &, unsigned int)

database()

class database & database ( ) const

inlinenoexcept

Returns the database to which this statement belongs.

Equivalent to sqlite3_db_handle

step()

bool step

(

)

Evaluate the statement.

Equivalent to sqlite3_step.

Returns true if a row was retrieved (SQLITE_ROW) or false if the statement has finished executing successfully (SQLITE_DONE).

All other sqlite3_step return codes result in exception being thrown

reset()

void reset ( )

inlinenoexcept

Reset the statement.

Equivalent to sqlite3_reset

busy()

bool busy ( ) const

inlinenoexcept

Determine if the statement has been reset.

Equivalent to sqlite3_stmt_busy

isexplain()

explain_type isexplain ( ) const

inlinenoexcept

Query the EXPLAIN Setting for the statement.

Equivalent to sqlite3_stmt_isexplain.

Since

SQLite 3.31

readonly()

bool readonly ( ) const

inlinenoexcept

Determine if the statement writes to the database.

Equivalent to sqlite3_stmt_readonly

bind() [1/11]

void bind ( int idx, std::nullptr_t  )

inline

Bind a NULL value to a parameter of the statement.

Equivalent to sqlite3_bind_null

bind() [2/11]

void bind ( int idx, int val )

inline

Bind an int value to a parameter of the statement.

Equivalent to sqlite3_bind_int

bind() [3/11]

void bind ( int idx, int64_t val )

inline

Bind an int64_t value to a parameter of the statement.

Equivalent to sqlite3_bind_int64

bind() [4/11]

void bind ( int idx, double val )

inline

Bind a double value to a parameter of the statement.

Equivalent to sqlite3_bind_double

bind() [5/11]

void bind	(	int	idx,
		const std::string_view &	val )

Bind a string value to a parameter of the statement.

Equivalent to sqlite3_bind_text with SQLITE_TRANSIENT.

The string content is used by value and copied into the statement. Thus the lifetime of the string referred to by value parameter is independent of the statement's

bind_reference() [1/6]

void bind_reference	(	int	idx,
		const std::string_view &	val )

Bind a string reference to a parameter of the statement.

Equivalent to sqlite3_bind_text with SQLITE_STATIC.

The string content is used by reference. Thus the string referred to by value parameter must remain valid during this statement's lifetime.

bind_reference() [2/6]

void bind_reference	(	int	idx,
		const std::string_view &	val,
		void(*	unref )(const char *) )

Bind a string reference to a parameter of the statement.

Equivalent to ::sqlite3_bind_text(..., unref)

The string content is used by reference.

Parameters

idx	index of the SQL parameter to be bound
val	reference to string to bind to the parameter
unref	called when the reference is no longer needed. Its argument is the pointer returned from value.data()

bind() [6/11]

void bind	(	int	idx,
		const std::u8string_view &	val )

Bind a string value to a parameter of the statement.

char8_t overload for bind(int, const std::string_view &)

bind_reference() [3/6]

void bind_reference	(	int	idx,
		const std::u8string_view &	val )

Bind a string reference to a parameter of the statement.

char8_t overload for bind_reference(int, const std::string_view &)

bind_reference() [4/6]

void bind_reference	(	int	idx,
		const std::u8string_view &	val,
		void(*	unref )(const char8_t *) )

Bind a string reference to a parameter of the statement.

char8_t overload for bind_reference(int, const std::string_view &, void (*)(const char *))

bind() [7/11]

void bind	(	int	idx,
		const blob_view &	val )

Bind a blob value to a parameter of the statement.

Equivalent to sqlite3_bind_blob with SQLITE_TRANSIENT.

The blob content is used by value and copied into the statement. Thus the lifetime of the blob referred to by value parameter is independent of the statement's

bind_reference() [5/6]

void bind_reference	(	int	idx,
		const blob_view &	val )

Bind a blob reference to a parameter of the statement.

Equivalent to sqlite3_bind_blob with SQLITE_STATIC.

The blob content is used by reference. Thus the string referred to by value parameter must remain valid during this statement's lifetime.

bind_reference() [6/6]

void bind_reference	(	int	idx,
		const blob_view &	val,
		void(*	unref )(const std::byte *) )

Bind a blob reference to a parameter of the statement.

Equivalent to sqlite3_bind_blob (..., unref)

The blob content is used by reference.

Parameters

idx	index of the SQL parameter to be bound
val	reference to blob to bind to the parameter
unref	called when the reference is no longer needed. Its argument is the pointer returned from value.data()

bind() [8/11]

void bind ( int idx, const zero_blob & val )

inline

Bind a blob of zeroes to a parameter of the statement.

Equivalent to sqlite3_bind_zeroblob.

bind() [9/11]

template<class T >

void bind ( int idx, T * ptr, const char * type, void(* destroy )(T *) )

inline

Bind a custom pointer to a parameter of the statement

Equivalent to sqlite3_bind_pointer.

The type parameter should be a static string, preferably a string literal.

bind() [10/11]

template<class T >

void bind ( int idx, std::unique_ptr< T > ptr )

inline

Bind a custom pointer to a parameter of the statement.

Equivalent to sqlite3_bind_pointer.

This is a safer overload of bind(int, T * , const char * , void( * )(T * )) that takes a pointer via std::unique_ptr ownership transfer. The inferred "type" for sqlite3_bind_pointer is typeid(T).name().

bind() [11/11]

void bind	(	int	idx,
		const value &	val )

Bind a dynamically typed value to a parameter of the statement.

Equivalent to sqlite3_bind_value.

clear_bindings()

void clear_bindings ( )

inlinenoexcept

Reset all bindings on the statement.

Equivalent to sqlite3_clear_bindings.

bind_parameter_count()

int bind_parameter_count ( ) const

inlinenoexcept

Returns the number of SQL parameters.

Equivalent to sqlite3_bind_parameter_count

bind_parameter_index()

int bind_parameter_index ( const string_param & name ) const

inlinenoexcept

Returns the index of a parameter with a given name.

Equivalent to sqlite3_bind_parameter_index

bind_parameter_name()

const char * bind_parameter_name ( int idx ) const

inlinenoexcept

Returns the name of a parameter with a given index.

Equivalent to sqlite3_bind_parameter_name

column_count()

int column_count ( ) const

inlinenoexcept

Number of columns in a result set.

Equivalent to sqlite3_column_count

Note that sqlite3_column_count represented by this function and sqlite3_data_count represented by data_count() are subtly and confusingly different. See their respective documentation for details.

See also

data_count

data_count()

int data_count ( ) const

inlinenoexcept

Number of columns in a result set.

Equivalent to sqlite3_data_count

Note that sqlite3_data_count represented by this function and sqlite3_column_count represented by column_count() are subtly and confusingly different. See their respective documentation for details.

See also

column_count

column_value()

template<class T >

T column_value ( int idx ) const

noexcept

Get result value from a query.

Wraps sqlite3_column_ function family. Unlike the C API you specify the desired type via T template parameter

Template Parameters

T	Desired output type. Must be one of: int int64_t double std::string_view std::u8string_view (if char8_t is supported by your compiler/library) blob_view

Parameters

idx	Column index

raw_column_value()

const value & raw_column_value ( int idx ) const

inlinenoexcept

Get result values from a query as a raw value object.

Equivalent to sqlite3_column_value

column_type()

int column_type ( int idx ) const

inlinenoexcept

Default datatype of the result column.

Equivalent to sqlite3_column_type

Returns

One of the SQLite fundamental datatypes

column_name()

const char * column_name ( int idx ) const

inlinenoexcept

Name of the result column.

Equivalent to sqlite3_column_name

The returned string pointer is valid until either the statement is destroyed or until the statement is automatically re-prepared by the first call to step() for a particular run or until the next call to column_name() on the same column.

column_database_name()

const char * column_database_name ( int idx ) const

inlinenoexcept

Database that is the origin of a result column.

Equivalent to sqlite3_column_database_name

column_table_name()

const char * column_table_name ( int idx ) const

inlinenoexcept

Table that is the origin of a result column.

Equivalent to sqlite3_column_table_name

column_origin_name()

const char * column_origin_name ( int idx ) const

inlinenoexcept

Table column that is the origin of a result column.

Equivalent to sqlite3_column_origin_name

column_declared_type()

const char * column_declared_type ( int idx ) const

inlinenoexcept

Declared datatype of a result column.

Equivalent to sqlite3_column_decltype

sql()

const char * sql ( ) const

inlinenoexcept

Returns a pointer to a copy of the SQL text used to create the statement.

Equivalent to sqlite3_sql

expanded_sql()

allocated_string expanded_sql

(

)

const

Returns SQL text of the statement with bound parameters expanded.

Equivalent to sqlite3_expanded_sql

Since

SQLite 3.14