libpqxx  7.7.2
pqxx::stateless_cursor< up, op > Class Template Reference

"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. More...
 
 stateless_cursor (transaction_base &tx, std::string_view adopted_cursor)
 Adopt an existing scrolling SQL cursor. More...
 
void close () noexcept
 Close this cursor. More...
 
size_type size ()
 Number of rows in cursor's result set. More...
 
result retrieve (difference_type begin_pos, difference_type end_pos)
 Retrieve rows from begin_pos (inclusive) to end_pos (exclusive) More...
 
constexpr std::string const & name () const noexcept
 Return this cursor's name. More...
 

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
txThe transaction within which you want to create the cursor.
queryThe SQL query whose results the cursor should traverse.
cnameA hint for the cursor's name. The actual SQL cursor's name will be based on this (though not necessarily identical).
holdCreate a WITH HOLD cursor? Such cursors stay alive after the transaction has ended, so you can continue to use it.

References pqxx::cursor_base::random_access.

◆ 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
txThe transaction within which you want to manage the cursor.
adopted_cursorYour 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
noexcept

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_posFirst 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_posRow 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.

◆ size()

template<cursor_base::update_policy up, cursor_base::ownership_policy op>
size_type pqxx::stateless_cursor< up, op >::size ( )

Number of rows in cursor's result set.

Note
This function is not const; it may need to scroll to find the size of the result set.

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