"Stateless cursor" class: easy API for retrieving parts of result sets More...

#include <cursor.hxx>

Public Types
using	size_type = result_size_type

using	difference_type = result_difference_type

Public Member Functions
	stateless_cursor (transaction_base &tx, std::string_view query, std::string_view cname, bool hold)
	Create cursor.

	stateless_cursor (transaction_base &tx, std::string_view adopted_cursor)
	Adopt an existing scrolling SQL cursor.

void	close () noexcept
	Close this cursor.

size_type	size ()
	Number of rows in cursor's result set.

result	retrieve (difference_type begin_pos, difference_type end_pos)
	Retrieve rows from begin_pos (inclusive) to end_pos (exclusive)

constexpr std::string const &	name () const noexcept
	Return this cursor's name.

Detailed Description

template<cursor_base::update_policy up, cursor_base::ownership_policy op>
class pqxx::stateless_cursor< up, op >

"Stateless cursor" class: easy API for retrieving parts of result sets

This is a front-end for SQL cursors, but with a more C++-like API.

Actually, stateless_cursor feels entirely different from SQL cursors. You don't keep track of positions, fetches, and moves; you just say which rows you want. See the retrieve() member function.

Member Typedef Documentation

◆ difference_type

template<cursor_base::update_policy up, cursor_base::ownership_policy op>

using pqxx::stateless_cursor< up, op >::difference_type = result_difference_type

◆ size_type

template<cursor_base::update_policy up, cursor_base::ownership_policy op>

using pqxx::stateless_cursor< up, op >::size_type = result_size_type

Constructor & Destructor Documentation

◆ stateless_cursor() [1/2]

template<cursor_base::update_policy up, cursor_base::ownership_policy op>

pqxx::stateless_cursor< up, op >::stateless_cursor	(	transaction_base &	tx,
		std::string_view	query,
		std::string_view	cname,
		bool	hold
	)

Create cursor.

Parameters

tx	The transaction within which you want to create the cursor.
query	The SQL query whose results the cursor should traverse.
cname	A hint for the cursor's name. The actual SQL cursor's name will be based on this (though not necessarily identical).
hold	Create a `WITH HOLD` cursor? Such cursors stay alive after the transaction has ended, so you can continue to use it.

◆ stateless_cursor() [2/2]

template<cursor_base::update_policy up, cursor_base::ownership_policy op>

pqxx::stateless_cursor< up, op >::stateless_cursor	(	transaction_base &	tx,
		std::string_view	adopted_cursor
	)

Adopt an existing scrolling SQL cursor.

This lets you define a cursor yourself, and then wrap it in a libpqxx-managed stateless_cursor object.

Parameters

tx	The transaction within which you want to manage the cursor.
adopted_cursor	Your cursor's SQL name.

References pqxx::cursor_base::backward_all().

Member Function Documentation

◆ close()

template<cursor_base::update_policy up, cursor_base::ownership_policy op>

void pqxx::stateless_cursor< up, op >::close ( )

noexcept

Close this cursor.

The destructor will do this for you automatically.

Closing a cursor is idempotent. Closing a cursor that's already closed does nothing.

◆ name()

template<cursor_base::update_policy up, cursor_base::ownership_policy op>

constexpr std::string const & pqxx::stateless_cursor< up, op >::name ( ) const

constexprnoexcept

Return this cursor's name.

◆ retrieve()

template<cursor_base::update_policy up, cursor_base::ownership_policy op>

result pqxx::stateless_cursor< up, op >::retrieve	(	difference_type	begin_pos,
		difference_type	end_pos
	)

Retrieve rows from begin_pos (inclusive) to end_pos (exclusive)

Rows are numbered starting from 0 to size()-1.

Parameters

begin_pos	First row to retrieve. May be one row beyond the end of the result set, to avoid errors for empty result sets. Otherwise, must be a valid row number in the result set.
end_pos	Row up to which to fetch. Rows are returned ordered from begin_pos to end_pos, i.e. in ascending order if begin_pos < end_pos but in descending order if begin_pos > end_pos. The end_pos may be arbitrarily inside or outside the result set; only existing rows are included in the result.

References pqxx::stateless_cursor< up, op >::size().