#include <SqlStatement.hpp>

Public Member Functions
LIGHTWEIGHT_FORCE_INLINE	SqlResultCursor (SqlStatement &stmt) noexcept
	Constructs a result cursor for the given SQL statement.

	SqlResultCursor (SqlResultCursor const &)=delete

SqlResultCursor &	operator= (SqlResultCursor const &)=delete

constexpr	SqlResultCursor (SqlResultCursor &&other) noexcept
	Move constructor.

constexpr SqlResultCursor &	operator= (SqlResultCursor &&other) noexcept
	Move assignment operator.

LIGHTWEIGHT_FORCE_INLINE size_t	NumRowsAffected () const
	Retrieves the number of rows affected by the last query.

LIGHTWEIGHT_FORCE_INLINE size_t	NumColumnsAffected () const
	Retrieves the number of columns affected by the last query.

LIGHTWEIGHT_API std::expected< SQLSMALLINT, SqlErrorInfo >	ColumnSqlType (SQLUSMALLINT column) const
	The SQL data type the driver reports for a result column (the `SQL_*` value from `SQLDescribeCol`), like RowArrayCursor::ColumnSqlType.

LIGHTWEIGHT_FORCE_INLINE void	ConsumePendingResults (std::source_location location=std::source_location::current())
	Steps through every result the last execution still has pending and throws for the first one that failed.

template<SqlOutputColumnBinder... Args>
LIGHTWEIGHT_FORCE_INLINE void	BindOutputColumns (Args *... args)

template<SqlOutputColumnBinder T>
LIGHTWEIGHT_FORCE_INLINE void	BindOutputColumn (SQLUSMALLINT columnIndex, T *arg)
	Binds a single output column at the given index to store fetched data.

LIGHTWEIGHT_FORCE_INLINE bool	FetchRow ()
	Fetches the next row of the result set.

LIGHTWEIGHT_FORCE_INLINE std::expected< bool, SqlErrorInfo >	TryFetchRow (std::source_location location=std::source_location::current()) noexcept
	Attempts to fetch the next row, returning an error info on failure instead of throwing.

template<typename... Records> requires (((std::is_class_v<Records> && std::is_aggregate_v<Records>) && ...))
LIGHTWEIGHT_FORCE_INLINE void	BindOutputColumnsToRecord (Records *... records)
	Binds the given records to the prepared statement to store the fetched data to.

template<typename Record , typename... ColumnAccessors>
LIGHTWEIGHT_FORCE_INLINE void	FetchAllRowWise (std::vector< Record > &out, std::size_t arrayDepth, ColumnAccessors const &... accessors)
	Fast bulk retrieval: materializes this result set into `out` via native ODBC row-wise array fetch. Forwards to `SqlStatement::FetchAllRowWise`; see its contract (eligibility and alignment preconditions are the caller's responsibility).

template<SqlGetColumnNativeType T>
LIGHTWEIGHT_FORCE_INLINE bool	GetColumn (SQLUSMALLINT column, T *result) const

template<SqlGetColumnNativeType T>
LIGHTWEIGHT_FORCE_INLINE T	GetColumn (SQLUSMALLINT column) const
	Retrieves the value of the column at the given index for the currently selected row.

template<SqlGetColumnNativeType T>
LIGHTWEIGHT_FORCE_INLINE std::optional< T >	GetNullableColumn (SQLUSMALLINT column) const

template<SqlGetColumnNativeType T>
T	GetColumnOr (SQLUSMALLINT column, T &&defaultValue) const

template<SqlGetColumnNativeType T>
LIGHTWEIGHT_FORCE_INLINE T	GetColumn (std::string_view name) const
	Retrieves the value of the named column for the currently selected row.

template<SqlGetColumnNativeType T>
LIGHTWEIGHT_FORCE_INLINE std::optional< T >	GetNullableColumn (std::string_view name) const
	Retrieves the value of the named column, or `std::nullopt` if it is NULL.

template<SqlGetColumnNativeType T>
T	GetColumnOr (std::string_view name, T &&defaultValue) const
	Retrieves the value of the named column, or `defaultValue` if it is NULL.

Detailed Description

API for reading an SQL query result set.

Definition at line 719 of file SqlStatement.hpp.

Constructor & Destructor Documentation

◆ SqlResultCursor() [1/2]

LIGHTWEIGHT_FORCE_INLINE Lightweight::SqlResultCursor::SqlResultCursor ( SqlStatement & stmt )

inlineexplicitnoexcept

Constructs a result cursor for the given SQL statement.

Definition at line 723 of file SqlStatement.hpp.

◆ SqlResultCursor() [2/2]

constexpr Lightweight::SqlResultCursor::SqlResultCursor ( SqlResultCursor && other )

inlineconstexprnoexcept

Move constructor.

Definition at line 733 of file SqlStatement.hpp.

◆ ~SqlResultCursor()

LIGHTWEIGHT_FORCE_INLINE Lightweight::SqlResultCursor::~SqlResultCursor ( )

inline

Definition at line 750 of file SqlStatement.hpp.

Member Function Documentation

◆ operator=()

constexpr SqlResultCursor & Lightweight::SqlResultCursor::operator= ( SqlResultCursor && other )

inlineconstexprnoexcept

Move assignment operator.

Definition at line 740 of file SqlStatement.hpp.

◆ NumRowsAffected()

LIGHTWEIGHT_FORCE_INLINE size_t Lightweight::SqlResultCursor::NumRowsAffected ( ) const

inline

Retrieves the number of rows affected by the last query.

Definition at line 760 of file SqlStatement.hpp.

Referenced by Lightweight::DataMapper::Delete().

◆ NumColumnsAffected()

LIGHTWEIGHT_FORCE_INLINE size_t Lightweight::SqlResultCursor::NumColumnsAffected ( ) const

inline

Retrieves the number of columns affected by the last query.

Definition at line 766 of file SqlStatement.hpp.

Referenced by Lightweight::DataMapper::Query().

◆ ColumnSqlType()

LIGHTWEIGHT_API std::expected< SQLSMALLINT, SqlErrorInfo > Lightweight::SqlResultCursor::ColumnSqlType ( SQLUSMALLINT column ) const

The SQL data type the driver reports for a result column (the SQL_* value from SQLDescribeCol), like RowArrayCursor::ColumnSqlType.

Parameters

column 1-based result column index.

Returns: The reported SQL_* type code, or the error (07009 for a column the result set does not have) if the column cannot be described.

◆ ConsumePendingResults()

LIGHTWEIGHT_FORCE_INLINE void Lightweight::SqlResultCursor::ConsumePendingResults ( std::source_location location = std::source_location::current() )

inline

Steps through every result the last execution still has pending and throws for the first one that failed.

A batch of several statements can report an error of a later statement only when its result is reached (on SQL Server, every statement that produces a row count is a result of its own). Closing the cursor discards those results without looking, because it must not throw. Call this after executing a batch whose failure must not go unnoticed.

Parameters

location The caller's source location, reported with the error.

Exceptions

SqlException A pending result reports an error.

Definition at line 779 of file SqlStatement.hpp.

◆ BindOutputColumns()

template<SqlOutputColumnBinder... Args>

LIGHTWEIGHT_FORCE_INLINE void Lightweight::SqlResultCursor::BindOutputColumns ( Args *... args )

inline

Binds the given arguments to the prepared statement to store the fetched data to.

The statement must be prepared before calling this function.

Definition at line 788 of file SqlStatement.hpp.

◆ BindOutputColumn()

template<SqlOutputColumnBinder T>

LIGHTWEIGHT_FORCE_INLINE void Lightweight::SqlResultCursor::BindOutputColumn	(	SQLUSMALLINT	columnIndex,
		T *	arg
	)

inline

Binds a single output column at the given index to store fetched data.

Definition at line 795 of file SqlStatement.hpp.

◆ FetchRow()

LIGHTWEIGHT_FORCE_INLINE bool Lightweight::SqlResultCursor::FetchRow ( )

inline

Fetches the next row of the result set.

Definition at line 801 of file SqlStatement.hpp.

Referenced by Lightweight::DataMapper::ConfigureRelationAutoLoading(), and Lightweight::DataMapper::Query().

◆ TryFetchRow()

LIGHTWEIGHT_FORCE_INLINE std::expected< bool, SqlErrorInfo > Lightweight::SqlResultCursor::TryFetchRow ( std::source_location location = std::source_location::current() )

inlinenoexcept

Attempts to fetch the next row, returning an error info on failure instead of throwing.

Definition at line 807 of file SqlStatement.hpp.

◆ BindOutputColumnsToRecord()

template<typename... Records>
requires (((std::is_class_v<Records> && std::is_aggregate_v<Records>) && ...))

LIGHTWEIGHT_FORCE_INLINE void Lightweight::SqlResultCursor::BindOutputColumnsToRecord ( Records *... records )

inline

Binds the given records to the prepared statement to store the fetched data to.

Definition at line 816 of file SqlStatement.hpp.

◆ FetchAllRowWise()

template<typename Record , typename... ColumnAccessors>

LIGHTWEIGHT_FORCE_INLINE void Lightweight::SqlResultCursor::FetchAllRowWise	(	std::vector< Record > &	out,
		std::size_t	arrayDepth,
		ColumnAccessors const &...	accessors
	)

inline

Fast bulk retrieval: materializes this result set into out via native ODBC row-wise array fetch. Forwards to SqlStatement::FetchAllRowWise; see its contract (eligibility and alignment preconditions are the caller's responsibility).

Parameters

out	Destination vector; results are appended.
arrayDepth	Requested maximum rows per `SQLFetchScroll` round-trip.
accessors	One invocable per result column; `accessor(record)` yields its mutable value.

Definition at line 828 of file SqlStatement.hpp.

◆ GetColumn() [1/3]

template<SqlGetColumnNativeType T>

LIGHTWEIGHT_FORCE_INLINE bool Lightweight::SqlResultCursor::GetColumn	(	SQLUSMALLINT	column,
		T *	result
	)		const

inline

Retrieves the value of the column at the given index for the currently selected row.

Returns true if the value is not NULL, false otherwise.

Definition at line 839 of file SqlStatement.hpp.

Referenced by Lightweight::DataMapper::ConfigureRelationAutoLoading(), and Lightweight::DataMapper::Query().

◆ GetColumn() [2/3]

template<SqlGetColumnNativeType T>

LIGHTWEIGHT_FORCE_INLINE T Lightweight::SqlResultCursor::GetColumn ( SQLUSMALLINT column ) const

inline

Retrieves the value of the column at the given index for the currently selected row.

Definition at line 846 of file SqlStatement.hpp.

◆ GetNullableColumn() [1/2]

template<SqlGetColumnNativeType T>

LIGHTWEIGHT_FORCE_INLINE std::optional< T > Lightweight::SqlResultCursor::GetNullableColumn ( SQLUSMALLINT column ) const

inline

Retrieves the value of the column at the given index for the currently selected row.

If the value is NULL, std::nullopt is returned.

Definition at line 855 of file SqlStatement.hpp.

◆ GetColumnOr() [1/2]

template<SqlGetColumnNativeType T>

T Lightweight::SqlResultCursor::GetColumnOr	(	SQLUSMALLINT	column,
		T &&	defaultValue
	)		const

inline

Retrieves the value of the column at the given index for the currently selected row.

If the value is NULL, the given defaultValue is returned.

Definition at line 864 of file SqlStatement.hpp.

◆ GetColumn() [3/3]

template<SqlGetColumnNativeType T>

LIGHTWEIGHT_FORCE_INLINE T Lightweight::SqlResultCursor::GetColumn ( std::string_view name ) const

inline

Retrieves the value of the named column for the currently selected row.

The name is the one spelled in the query builder that composed this query — a bare column name for Field("x"), the qualified "table.column" for Field({"table", "x"}), or the alias for an aliased projection. Only builder-composed queries carry a mapping.

Note: Reads must still ascend in column order: the SQL Server driver rejects out-of-order SQLGetData with SQLSTATE 07009, and addressing columns by name makes it easy to reorder them inadvertently.

Parameters

name	The column name as spelled in the query builder.

Returns: The column value converted to T.

Exceptions

std::invalid_argument If no mapping is available, or name is unknown or ambiguous.

Definition at line 883 of file SqlStatement.hpp.

◆ GetNullableColumn() [2/2]

template<SqlGetColumnNativeType T>

LIGHTWEIGHT_FORCE_INLINE std::optional< T > Lightweight::SqlResultCursor::GetNullableColumn ( std::string_view name ) const

inline

Retrieves the value of the named column, or std::nullopt if it is NULL.

The name is the one spelled in the query builder that composed this query; only builder-composed queries carry a mapping. Reads must ascend in column order — see the name-taking GetColumn.

Parameters

name	The column name as spelled in the query builder.

Returns: The column value converted to T, or std::nullopt if the column is NULL.

Exceptions

std::invalid_argument If no mapping is available, or name is unknown or ambiguous.

Definition at line 897 of file SqlStatement.hpp.

◆ GetColumnOr() [2/2]

template<SqlGetColumnNativeType T>

T Lightweight::SqlResultCursor::GetColumnOr	(	std::string_view	name,
		T &&	defaultValue
	)		const

inline

Retrieves the value of the named column, or defaultValue if it is NULL.

The name is the one spelled in the query builder that composed this query; only builder-composed queries carry a mapping. Reads must ascend in column order — see the name-taking GetColumn.

Parameters

name	The column name as spelled in the query builder.
defaultValue	The value to return when the column is NULL.

Returns: The column value converted to T, or defaultValue if the column is NULL.

Exceptions

std::invalid_argument If no mapping is available, or name is unknown or ambiguous.

Definition at line 912 of file SqlStatement.hpp.

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

Lightweight/SqlStatement.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SqlResultCursor() [1/2]

◆ SqlResultCursor() [2/2]

◆ ~SqlResultCursor()

Member Function Documentation

◆ operator=()

◆ NumRowsAffected()

◆ NumColumnsAffected()

◆ ColumnSqlType()

◆ ConsumePendingResults()

◆ BindOutputColumns()

◆ BindOutputColumn()

◆ FetchRow()

◆ TryFetchRow()

◆ BindOutputColumnsToRecord()

◆ FetchAllRowWise()

◆ GetColumn() [1/3]

◆ GetColumn() [2/3]

◆ GetNullableColumn() [1/2]

◆ GetColumnOr() [1/2]

◆ GetColumn() [3/3]

◆ GetNullableColumn() [2/2]

◆ GetColumnOr() [2/2]