vtab< Derived > Class Template Reference

Base class for virtual table object implementations. More...

Inheritance diagram for vtab< Derived >:

Classes
struct	connect_t
	Marker type that tells the constructor of Derived to be used to connect to an existing table. More...
struct	create_t
	Marker type that marks the constructor of Derived to be used to create a new table. More...
class	cursor
	Base class for cursors. More...

Public Types
using	constructor_data_type = void
	Type of data passed via create_module to the constructor(s)
using	index_data_type = void
	Type of data stored in index_info and passed between best_index and cursor::filter.

Public Member Functions
template<class D = Derived>
bool	best_index (index_info< typename D::index_data_type > &info) const
	Determines the best way to access the virtual table.
template<class D = Derived>
std::unique_ptr< typename D::cursor >	open ()
	Creates a new cursor used for accessing the virtual table.

Static Public Member Functions
static void	create_module (database &db, const string_param &name)
	Register a virtual table implementation with a database connection.
template<class D = Derived>
static void	create_module (database &db, const string_param &name, typename D::constructor_data_type data, void(*destructor)(typename D::constructor_data_type)=nullptr)
	Register a virtual table implementation with a database connection.
template<class D = Derived>
static void	create_module (database &db, const string_param &name, std::unique_ptr< std::remove_pointer_t< typename D::constructor_data_type > > data)
	Register a virtual table implementation with a database connection.
static sqlite3_module *	get_module ()
	Obtains the singleton sqlite3_module for this virtual table.

Protected Member Functions
	vtab ()
	This class is default constructible only by derived classes.
	vtab (const vtab &)=delete
	You cannot copy (or move) this class.
vtab &	operator= (const vtab &)=delete
	You cannot assign this class.
	~vtab ()
	This class is destructible only by derived classes.

Detailed Description

template<class Derived>
class thinsqlitepp::vtab< Derived >

Base class for virtual table object implementations.

This class greatly simplifies development of virtual tables by encapsulating management of sqlite3_module, providing type safety, error handling and RAII and reasonable defaults.

It is intended to be used as CRTP base class for your own virtual table implementations.

Important

This documentation only describes the base class interface. Please refer to Implementing Virtual Tables for detailed information about how to create classes derived from vtab to implement virtual tables.

#include <thinsqlitepp/vtab.hpp>

---

Class Documentation

thinsqlitepp::vtab::connect_t

struct thinsqlitepp::vtab::connect_t

template<class Derived>
struct thinsqlitepp::vtab< Derived >::connect_t

Marker type that tells the constructor of Derived to be used to connect to an existing table.

thinsqlitepp::vtab::create_t

struct thinsqlitepp::vtab::create_t

template<class Derived>
struct thinsqlitepp::vtab< Derived >::create_t

Marker type that marks the constructor of Derived to be used to create a new table.

Member Typedef Documentation

constructor_data_type

template<class Derived >

using constructor_data_type = void

Type of data passed via create_module to the constructor(s)

You can override this default by declaring a different typedef in your derived class

The default is void, meaning no data is stored and passed

index_data_type

template<class Derived >

using index_data_type = void

Type of data stored in index_info and passed between best_index and cursor::filter.

You can override this default by declaring a different typedef in your derived class.

The default is void, meaning no data is stored and passed

Member Function Documentation

create_module() [1/3]

template<class Derived >

static void create_module ( database & db, const string_param & name )

inlinestatic

Register a virtual table implementation with a database connection.

Equivalent to sqlite3_create_module_v2

If constructor_data_type is not void using this method causes nullptr to be passed to derived class constructor.

Parameters

db	database to register the implementation with
name	module name

create_module() [2/3]

template<class Derived >

template<class D = Derived>

static void create_module ( database & db, const string_param & name, typename D::constructor_data_type data, void(* destructor )(typename D::constructor_data_type) = nullptr )

inlinestatic

Register a virtual table implementation with a database connection.

Equivalent to sqlite3_create_module_v2

This overload is available if constructor_data_type is not void.

Template Parameters

D	Defers resolution of nested data types declared in derived class. This is an internal implementation detail - never specify it explicitly.

Parameters

db	database to register the implementation with
name	module name
data	data to be passed to your derived class constructor. Can be nullptr. You can change the type of the data by re-defining constructor_data_type in your derived class.
destructor	an optional destructor function for the data pointer. Can be nullptr.

create_module() [3/3]

template<class Derived >

template<class D = Derived>

static void create_module ( database & db, const string_param & name, std::unique_ptr< std::remove_pointer_t< typename D::constructor_data_type > > data )

inlinestatic

Register a virtual table implementation with a database connection.

Equivalent to sqlite3_create_module_v2

This overload is available if constructor_data_type is not void.

Template Parameters

D	Defers resolution of nested data types declared in derived class. This is an internal implementation detail - never specify it explicitly.

Parameters

db	database to register the implementation with
name	module name
data	data to be passed to your derived class constructor. Can be nullptr. You can change the type of the data by re-defining constructor_data_type in your derived class.

best_index()

template<class Derived >

template<class D = Derived>

bool best_index ( index_info< typename D::index_data_type > & info ) const

inline

Determines the best way to access the virtual table.

Equivalent to xBestIndex

Re-define this method in your derived class. Your implementation can throw exceptions to indicate errors.

This method communicates information to SQLite as well cursor::filter. This default implementation does essentially nothing and allows all filters.

Template Parameters

D	Defers resolution of nested data types declared in derived class. This is an internal implementation detail - your re-defined implementations do not need to be templated.

Parameters

info	The SQLite core communicates with the best_index method by populating fields of the index_info passing it to best_index. The best_index method fills out writable fields of this object which forms the reply.

Returns

true on success or false if the particular combination of input parameters specified is insufficient for the virtual table to do its job. This is logically the same as calling the index_info::set_estimated_cost with an infinity. If every call to best_index for a particular query plan returns false, that means there is no way for the virtual table to be safely used, and the statement::create() call will fail with a "no query solution" error. Returning false is equivalent to returning SQLITE_CONSTRAINT from xBestIndex.

open()

template<class Derived >

template<class D = Derived>

std::unique_ptr< typename D::cursor > open ( )

inline

Creates a new cursor used for accessing the virtual table.

Equivalent to xOpen

If your cursor Derived::cursor class constructor has the form cursor::cursor(Derived *) you do not need to re-define this function. Otherwise re-define it to create cursor in the appropriate way. Your implementation can throw exceptions to indicate errors.

Template Parameters

D	Defers resolution of nested data types declared in derived class. This is an internal implementation detail - your re-defined implementations do not need to be templated.

Returns

A unique pointer to the cursor instance

get_module()

template<class Derived >

static sqlite3_module * get_module ( )

static

Obtains the singleton sqlite3_module for this virtual table.

Usually you do not need to call this function. It can be used to obtain sqlite3_module instance for your derived class if you plan to use it manually via database::create_module or sqlite3_create_module_v2