Forward-only cursor over the rows produced by a prepared statement. More...

#include <result.hpp>

Collaboration diagram for sqlite::v2::result:

Public Member Functions
	~result ()
	Destroys the cursor but leaves the underlying statement intact if it is still shared.
bool	next_row ()
	Advances to the next row.
bool	end () const
	Checks whether next_row already consumed the last row.
void	reset ()
	Resets the cursor to the beginning without re-binding parameters.
int	get_changes ()
	Returns the number of rows affected by the statement.
int	get_column_count ()
	Returns the number of columns exposed by the current statement.
type	get_column_type (int idx)
	Reports the SQLite storage class for the value at index `idx`.
std::string	get_column_decltype (int idx)
	Returns the declared type of the column at index `idx`.
variant_t	get_variant (int index)
	Materializes the current value as variant_t.
size_t	get_binary_size (int idx)
	Reports the number of bytes stored in column `idx`.
void	get_binary (int idx, void *buf, size_t buf_size)
	Copies a blob column into the caller-provided buffer.
void	get_binary (int idx, std::vector< unsigned char > &vec)
	Retrieves a blob column into a std::vector<unsigned char>.
std::span< const unsigned char >	get_binary_span (int idx)
	Returns a span that references the blob contents without copying.
std::string	get_column_name (int idx)
	Returns the UTF-8 column name declared in the statement.
bool	is_null (int idx)
	Tests whether the value at column `idx` is SQL NULL.
template<typename T>
T	get (int idx)
	Extracts the column at `idx` into an arbitrary C++ type.
template<typename... Ts>
std::tuple< Ts... >	get_tuple (int start_column=0)
	Collects a contiguous slice of columns into a std::tuple.

Private Types
typedef std::shared_ptr< result_construct_params_private >	construct_params

Private Member Functions
	result (construct_params)
	result (result const &)=delete
result &	operator= (result const &)=delete
void	access_check (int)
int	get_int (int idx)
std::int64_t	get_int64 (int idx)
std::string	get_string (int idx)
std::string_view	get_string_view (int idx)
double	get_double (int idx)

Private Attributes
construct_params	m_params
int	m_columns

Friends
struct	query

Detailed Description

Forward-only cursor over the rows produced by a prepared statement.

Instances are created and owned by query and encapsulate the currently bound statement plus its execution state. The cursor is non-copyable, but it keeps the underlying resources alive through shared ownership until both the query and the result go out of scope.

Definition at line 75 of file result.hpp.

Member Typedef Documentation

◆ construct_params

typedef std::shared_ptr<result_construct_params_private> sqlite::v2::result::construct_params

private

Definition at line 77 of file result.hpp.

Constructor & Destructor Documentation

◆ result() [1/2]

sqlite::v2::result::result ( construct_params )

private

Referenced by operator=(), and result().

◆ result() [2/2]

sqlite::v2::result::result ( result const & )

privatedelete

References result().

Here is the call graph for this function:

◆ ~result()

sqlite::v2::result::~result ( )

Destroys the cursor but leaves the underlying statement intact if it is still shared.

Member Function Documentation

◆ access_check()

void sqlite::v2::result::access_check ( int )

private

◆ end()

bool sqlite::v2::result::end ( ) const

inline

Checks whether next_row already consumed the last row.

Returns: true when the cursor is positioned after the final row.

Exceptions

std::runtime_error if the result is no longer valid.

Definition at line 101 of file result.hpp.

References sqlite::v2::detail::end(), and m_params.

Here is the call graph for this function:

◆ get()

template<typename T>

T sqlite::v2::result::get ( int idx )

Extracts the column at idx into an arbitrary C++ type.

Supported conversions include:

arithmetic types (integral, floating point, enums, bool)
std::string and std::string_view
std::chrono::duration / time_point stored as microseconds
std::optional<T> for nullable fields
byte arrays (std::vector<unsigned char>, std::span<const unsigned char>, std::span<const std::byte>)

Parameters

idx	Zero-based column index.

Template Parameters

T	Desired destination type.

Exceptions

database_exception	or std::out_of_range when `idx` is invalid.
buffer_too_small_exception	if the requested type requires more space than available.

Definition at line 261 of file result.hpp.

References sqlite::v2::detail::always_false_v, sqlite::v2::blob, get(), get_binary(), get_binary_span(), get_double(), get_int(), get_int64(), get_string(), get_string_view(), sqlite::v2::detail::is_byte_span_v, sqlite::v2::detail::is_byte_vector_v, sqlite::v2::detail::is_duration_v, is_null(), sqlite::v2::detail::is_optional_v, sqlite::v2::detail::is_time_point_v, and sqlite::v2::detail::is_unsigned_char_span_v.

Referenced by sqlite::v2::query::result_range::row_view::get(), sqlite::v2::query::result_range::row_view::get(), and get().

Here is the call graph for this function:

◆ get_binary() [1/2]

void sqlite::v2::result::get_binary	(	int	idx,
		std::vector< unsigned char > &	vec )

Retrieves a blob column into a std::vector<unsigned char>.

Parameters

idx	Zero-based column index.
vec	Destination buffer that will be resized to match the blob length.

◆ get_binary() [2/2]

void sqlite::v2::result::get_binary	(	int	idx,
		void *	buf,
		size_t	buf_size )

Copies a blob column into the caller-provided buffer.

Parameters

idx	Zero-based column index.
buf	Destination memory.
buf_size	Capacity of `buf` in bytes.

Exceptions

buffer_too_small_exception when buf_size is smaller than the blob.

Referenced by get().

◆ get_binary_size()

size_t sqlite::v2::result::get_binary_size ( int idx )

Reports the number of bytes stored in column idx.

Parameters

idx	Zero-based column index.

Returns: Length in bytes, or 0 when the column is NULL. Only meaningful for BLOB/TEXT columns; other types return the storage size SQLite reports.

◆ get_binary_span()

std::span< const unsigned char > sqlite::v2::result::get_binary_span ( int idx )

Returns a span that references the blob contents without copying.

The span becomes invalid as soon as the cursor advances or resets.

Referenced by get().

◆ get_changes()

int sqlite::v2::result::get_changes ( )

Returns the number of rows affected by the statement.

Mirrors sqlite3_changes() and therefore only applies to INSERT, UPDATE, or DELETE statements. To count the rows returned by a SELECT, issue a separate SELECT COUNT(*) ... query.

◆ get_column_count()

int sqlite::v2::result::get_column_count ( )

Returns the number of columns exposed by the current statement.

Returns: Number of columns (>= 0). This value never changes while the result lives.

◆ get_column_decltype()

std::string sqlite::v2::result::get_column_decltype ( int idx )

Returns the declared type of the column at index idx.

The result mirrors sqlite3_column_decltype and therefore reflects the schema's declared affinity (e.g. "INTEGER" or "TEXT").

◆ get_column_name()

std::string sqlite::v2::result::get_column_name ( int idx )

Returns the UTF-8 column name declared in the statement.

Parameters

idx	Zero-based column index.

◆ get_column_type()

type sqlite::v2::result::get_column_type ( int idx )

Reports the SQLite storage class for the value at index idx.

Parameters

idx	Zero-based column index.

Returns: A value from the type enumeration.

Exceptions

std::out_of_range when idx is outside [0, get_column_count()).

◆ get_double()

double sqlite::v2::result::get_double ( int idx )

private

Referenced by get().

◆ get_int()

int sqlite::v2::result::get_int ( int idx )

private

Referenced by get().

◆ get_int64()

std::int64_t sqlite::v2::result::get_int64 ( int idx )

private

Referenced by get().

◆ get_string()

std::string sqlite::v2::result::get_string ( int idx )

private

Referenced by get().

◆ get_string_view()

std::string_view sqlite::v2::result::get_string_view ( int idx )

private

Referenced by get().

◆ get_tuple()

template<typename... Ts>

std::tuple< Ts... > sqlite::v2::result::get_tuple ( int start_column = 0 )

Collects a contiguous slice of columns into a std::tuple.

Parameters

start_column First column to include; defaults to 0.

Template Parameters

Ts	Types to extract, matched positionally from `start_column`.

Returns: Tuple whose arity matches the template parameters.

Exceptions

database_exception when the tuple would exceed the column count.

Definition at line 304 of file result.hpp.

References m_columns, and sqlite::v2::detail::tuple_from_row().

Here is the call graph for this function:

◆ get_variant()

variant_t sqlite::v2::result::get_variant ( int index )

Materializes the current value as variant_t.

Parameters

index Zero-based column index.

Returns: A populated variant storing one of the supported SQLite types.

◆ is_null()

bool sqlite::v2::result::is_null ( int idx )

Tests whether the value at column idx is SQL NULL.

Parameters

idx	Zero-based column index.

Referenced by get().

◆ next_row()

bool sqlite::v2::result::next_row ( )

Advances to the next row.

Returns: true when a fresh row is available, false when the result set is exhausted.

Exceptions

std::runtime_error if the underlying statement was already destroyed.

◆ operator=()

result & sqlite::v2::result::operator= ( result const & )

privatedelete

References result().

Here is the call graph for this function:

◆ reset()

void sqlite::v2::result::reset ( )

inline

Resets the cursor to the beginning without re-binding parameters.

Use this when you need to re-iterate the same result set after calling next_row.

Exceptions

std::runtime_error if the result is no longer valid.

Definition at line 113 of file result.hpp.

References m_params, and sqlite::v2::detail::reset().

Here is the call graph for this function:

◆ query

friend struct query

friend

Definition at line 78 of file result.hpp.

References query.

Referenced by query.

Member Data Documentation

◆ m_columns

int sqlite::v2::result::m_columns

private

Definition at line 248 of file result.hpp.

Referenced by get_tuple().

◆ m_params

construct_params sqlite::v2::result::m_params

private

Definition at line 247 of file result.hpp.

Referenced by end(), and reset().

The documentation for this struct was generated from the following file:

include/sqlite/result.hpp

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ construct_params

Constructor & Destructor Documentation

◆ result() [1/2]

◆ result() [2/2]

◆ ~result()

Member Function Documentation

◆ access_check()

◆ end()

◆ get()

◆ get_binary() [1/2]

◆ get_binary() [2/2]

◆ get_binary_size()

◆ get_binary_span()

◆ get_changes()

◆ get_column_count()

◆ get_column_decltype()

◆ get_column_name()

◆ get_column_type()

◆ get_double()

◆ get_int()

◆ get_int64()

◆ get_string()

◆ get_string_view()

◆ get_tuple()

◆ get_variant()

◆ is_null()

◆ next_row()

◆ operator=()

◆ reset()

Friends And Related Symbol Documentation

◆ query

Member Data Documentation

◆ m_columns

◆ m_params