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 ) noexcept)
	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 ) noexcept)
	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 ) noexcept)
	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, class D>
void	bind (int idx, T ptr, const char type, D destroy)

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.

Binding carray() values to parameters
This set of overloaded functions wraps sqlite3_carray_bind and sqlite3_carray_bind_v2 functions.
template<class T>
void	carray_bind (int idx, span< T > array)
	Bind the content of an array for the CARRAY table-valued function in the statement.
template<class T>
void	carray_bind_reference (int idx, span< T > array)
	Bind a reference to an array for the CARRAY table-valued function in the statement.
template<class T>
void	carray_bind (int idx, span< T > array, void(destroy)(void ) noexcept, void *destroy_arg=nullptr)
	Bind a reference to an array for the CARRAY table-valued function in the statement.

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]

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]

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]

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]

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

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

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

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, class D>

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

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.

◆ carray_bind() [1/2]

template<class T>

void carray_bind	(	int	idx,
		span< T >	array )

inline

Bind the content of an array for the CARRAY table-valued function in the statement.

Equivalent to sqlite3_carray_bind_v2 with SQLITE_TRANSIENT.

The span content is copied into the statement. Thus the lifetime of the data referred to by array parameter is independent of the statement's

Template Parameters

T	Array content type. Can be one of: int int64_t double char * char8_t * (if char8_t is supported by your compiler/library) iovec

◆ carray_bind_reference()

template<class T>

void carray_bind_reference	(	int	idx,
		span< T >	array )

inline

Bind a reference to an array for the CARRAY table-valued function in the statement.

Equivalent to sqlite3_carray_bind_v2 with SQLITE_STATIC.

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

Template Parameters

T	Array content type. Can be one of: int int64_t double char * char8_t * (if char8_t is supported by your compiler/library) iovec

◆ carray_bind() [2/2]

template<class T>

void carray_bind	(	int	idx,
		span< T >	array,
		void(*	destroy )(void *) noexcept,
		void *	destroy_arg = nullptr )

inline

Bind a reference to an array for the CARRAY table-valued function in the statement.

Equivalent to sqlite3_carray_bind_v2

The span content is used by reference. The destroy function will be invoked by SQLite when it is safe to dispose of the array data (on both success and failure).

Template Parameters

T	Array content type. Can be one of: int int64_t double char * char8_t * (if char8_t is supported by your compiler/library) iovec

◆ 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

Public Types

Public Member Functions

Static Public Member Functions

Binding carray() values to parameters

Detailed Description

Member Enumeration Documentation

◆ explain_type

Member Function Documentation

◆ create() [1/4]

◆ create() [2/4]

◆ create() [3/4]

◆ create() [4/4]

◆ database()

◆ step()

◆ reset()

◆ busy()

◆ isexplain()

◆ readonly()

◆ bind() [1/11]

◆ bind() [2/11]

◆ bind() [3/11]

◆ bind() [4/11]

◆ bind() [5/11]

◆ bind_reference() [1/6]

◆ bind_reference() [2/6]

◆ bind() [6/11]

◆ bind_reference() [3/6]

◆ bind_reference() [4/6]

◆ bind() [7/11]

◆ bind_reference() [5/6]

◆ bind_reference() [6/6]

◆ bind() [8/11]

◆ bind() [9/11]

◆ bind() [10/11]

◆ bind() [11/11]

◆ carray_bind() [1/2]

◆ carray_bind_reference()

◆ carray_bind() [2/2]

◆ clear_bindings()

◆ bind_parameter_count()

◆ bind_parameter_index()

◆ bind_parameter_name()

◆ column_count()

◆ data_count()

◆ column_value()

◆ raw_column_value()

◆ column_type()

◆ column_name()

◆ column_database_name()

◆ column_table_name()

◆ column_origin_name()

◆ column_declared_type()

◆ sql()

◆ expanded_sql()